Download BACHELOR THESIS

3.7 Documentation
Any source code that should be easily modifiable (extensible) needs to be
documented. For a project as large as AsM, the code documentation is not sufficient;
more accessible documentation has to be available as well. A common way to
provide such documentation is to automatically generate the developer
documentation from a specifically formatted code documentation. However, every
programming language is different; therefore, many of them have their own
formatting rules and documentation tools. This section describes the tools used by
the AsM project to generate common developer documentation for the whole
project.
AsM project is composed of parts written in different programming languages,
mostly in PHP and JavaScript. PHP has a formal code documentation standard,
PHPDoc, which is described in [14]. It not only allows to generate a separate
documentation using external tools such as phpDocumentor, but it also lets IDEs21
provide various convenient features, e.g. code completion. JavaScript, being a very
different programming language altogether, has no such standard. While it would be
possible to generate separate documentation for each part of the AsM project (the
Core and the UI being the most important), it would be quite restrictive, e.g. crossreferencing between parts would become a problem. Additionally, using different
tools for each part would require spending additional time studying how to use those
tools. Instead, a decision was made to use a single tool for generating documentation
for the whole project, providing that there is one which meets the following
requirements.
 PHP documentation format should resemble PHPDoc format, so that the IDEs
could understand it as such.
 There should be little or no difference between the JavaScript and PHP code
documentation formatting.
 Modification of the tool for this purpose should be less costly, i.e. timeconsuming, than creation and maintenance of documentation in two different
formats.
The tool selected on the basis of these requirements, Doxygen, is the most widely
used source code documentation tool nowadays. It supports a wide range of
programming languages and it is highly customizable. Doxygen formatting can be
customized to resemble PHPDoc formatting enough to pass for one (see [15]).
Unfortunately, JavaScript is not supported by Doxygen, because in general, the
JavaScript code has very loose structure. To remedy this, the AsM project includes a
21
Integrated Development Environment (IDE) is an application providing a comprehensive
set of tools for software developers, including a source code editor, a compiler, and a
debugger. Commonly used IDEs include NetBeans, Microsoft Visual Studio, or Eclipse.
57