Software Document Generator

Software to report or document the Software sources of computer systems. The goal is to create an HTML or PDF which gives a complete picture of the state of the software until now. The process needs to be repeatable. The process uses the sources. The process may use external information which explains the building and maintenance.

Introduction

The creation of software documentation is a very important part of the software development. Creating the software documentation forces the developer to explain why and how he has made his solution. The tooling makes it possible to create documentation that can be read by many people without distributing the software sources.

Pro: - Forces developers to document. - Is always up-to-date by using i.e. continuous build. - Enables the project-leader or the architect to review Con: - The software document generator tools can not manage all languages. - The tooling lacks combined solution (i.e. php and javascript combined and working together). - Mostly OO driven software, less powerful in procedural software (i.e. not in classes).

Tooling

The list of tools is large . On this page only tools that can parse PHP and/or JavaScript are covered.

• Doxygen, Webpage stack.nl/~dimitri/doxygen.
• JsDoc or UseJSDoc, Webpage usejsdoc.org

Doxygen

Doxygen creator Dimitri van Hees declares on his website: Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D.

Doxygen is a great tool and the parsed code and generated output HTML/PDF/Latex/RTF/Word is fine. The biggest disadvantage is it cannot manage JavaScript. That means also that files that embed JavaScript are not parsed well and information is lost. Nowadays the combination of a language (i.e. PHP as Server language and JavaScript as Client language) uses techniques to parse PHP variables to JavaScript. Very important if the Website uses AJAX a lot.

UseJSDoc

What applies to Doxygen applies also for UseJSDoc. The tool is good for JavaScript but that is all it can handle.