ALMA Software Engineering

DOXYGEN GUIDELINES FOR ALMA-SW

User Manual

USAGE SUGGESTION:

the target in the makefile will be used to locally generate information which relates to the current module only. This will enable each user of a module to retrieve it from the archive and access its documentation with a web browser after having done a 'make man'

A different story is the generation of a documentation spreading over several modules. This will be done at package level (ACS, TICS etc.) and will be taken care of by the corresponding *BUILD modules.

SUGGESTED IMPLEMENTATION PHASES:

doxygen for html only, module level

doxygen for html only, package (TICS, ACS, etc.) level

doxygen for PDF files test

doxygen for manpages

---

1. a unique doxygen configuration file is stored in in the acs module, to serve as an all purpose generic doxygen configuration file

2. the 'man' target for the acsMakefile/vltMakefile is extended so that if doxygen is available, it is used to generate documentation. This implies that the common doxygen configuration file is extracted, modified according to some pattern replacement (see below), then doxygen is called one or more times, once for each 'include', 'idl', and 'src' (possibly also modifying the INPUT keyword)

3. directories structure will be:

      <module>/ws/doc/html/api     from include and src directory
         .         .       idl      from idl directory
         .         . /man/api
         .             . /idl    
         .    /lcu/doc/html/api     from include and src directory
                    .       idl     from idl directory
                    . /man/api
                        . /idl    
   

4. Some features of the generic configuration file:
   • Javadoc will be the style used
   • JAVA_AUTODOCBRIEF is set to yes
   • EXTRACT_ALL is set to yes, and so are EXTRACT_PRIVATE and EXTRACT_STATIC
   • the file selection pattern (FILE_PATTERNS) will be chosen to contain *.h *.idl *.java *.cpp *.c
5. documentation should not be archived with a module, but regenerated each time

QUESTIONS TO BE CLEARED:

• how do we avoid doxygen generataing manpages also for non-application files? It also remains to be seen whether the doxygen performs better than 'docDoManPages', currently still used by the VLT Project.