Documenting AstroBEAR

Doxygen is a tool for turning inline documentation into html documents for easier viewing of code/comments. There are two doxygen config files in the code repository that can be used to produce documentation.

• To generate documentation for the wiki, run doxygen dox-config-scrambler. This will create a doc directory containing html source. This should then be copied to /cloverdata/trac/astrobear/doc/doxygen so it can be viewed using the Doxygen tab.
• Running doxygen dox-config-scrambler-with-warnings will produce a file dox-warnlog.txt which can be used to check for documentation related warnings.

Doxygen is a bit fickle especially when it comes to fortran so there are a few things to be aware of.

• All doxygen comment blocks should begin with a '!>'. Successive lines can begin with a '!!'. Doxygen will ignore the following

    !! @brief Description of module
    !! @author Joe Schmoe
  
    Module SampleModule
  

• All comment blocks by default will describe the next fortran entity (module, function, type definition, variable). You can however have a comment block describe a different entity by describing the entity in the first line using (@file, @var, @typedef, @fn) etc. This is necessary for files

  !> @file SampleFile.f90
  !! @brief Brief description of file
  !! @details Detailed description of file
  !! @author Joe Schmoe
  

• Doxygen does not seem to correctly include files - which is very annoying. However, doxygen will automatically link text that matches the names of entities (like the wiki). So include files should be explicitly stated in the module description.

  !> @brief Brief description of module.
  !! @details Longer Description of module
  !! @par Include Files:
  !! doxygen_example_include_file.f90 \n
  !! @author Module Author Name and Affiliation
  !! @ingroup DoxygenExampleGroup
  module Doxygen_Examples
  

  We've used the @par command within the details section to start a new paragraph titled 'Include Files'. Again this should be done automatically by doxygen - but for now this seems to be the best workaround.
• It is also a good idea to link include files to the module they are included in. This can be done in the description of the include file

  !> @file doxygen_example_include_file.f90
  !> @brief Include file for module Doxygen_Examples
  !> @details More in depth description of this file
  

• You may have noticed the @ingroup tag in the next to last example. Doxygen allows you to put things in groups for organizational purposes. Unfortunately Doxygen refers to these groups as modules - which is confusing since modules also refers to the fortran entities. This is the reason that there are two 'modules' tabs. You can group modules, functions, variables, etc… and you can put groups inside of other groups. Doxygen claims to support putting objects in more than one group - but I have not been able to get this to work. Again to emphasize, groups have nothing to do with fortran dependencies - but are just a convenient way to organize functions/modules/variables for browsing.

• You can put things into 'groups in two ways
  • Directly specify a group in the comment block of an object by adding the @ingroup tag as seen above.
  • Wrap the object(s) using '@{' and '@}' following either the group definition '@defgroup' or an '@addtogroup' tag.

       !> @defgroup ExampleFunctions Example Functions
       !! @{
    
       !> @brief Brief description of routine.
       !> @details Flow method (rate of change of position) used by integrator.
       !> Compute \f$ \frac{d\lambda}{dt} , \frac{d\phi}{dt},  \frac{dz}{dt} \f$
       !> @author Routine Author Name and Affiliation.
       !> @param[in] x
       !> @param[out] y
       SUBROUTINE f(x,y)
         REAL :: x
         REAL :: y
         y=x**2
       END SUBROUTINE f
    
    
       !> @brief Brief description of routine.
       !> @details Flow method (rate of change of position) used by integrator.
       !! Compute \f$ \frac{d\lambda}{dt} , \frac{d\phi}{dt},  \frac{dz}{dt} \f$
       !> @author  Routine Author Name and Affiliation.
       !> @param[in] x
       !> @param[out] y
       SUBROUTINE g(x,y)
         REAL :: x
         REAL :: y
         y=x**2
       END SUBROUTINE g
    
     !> @}
    
    

• If we had functions in another file that we wanted to include in this group we could use the @addtogroup tag:

   !> @addtogroup ExampleFunctions
     !! @{
  
     !> @name hi_functions hi functions
     !! @brief Brief Description of the member group hi functions
     !! @{
  
     !> @brief Brief description of routine.
     !> @details Flow method (rate of change of position) used by integrator.
     !! Compute \f$ \frac{d\lambda}{dt} , \frac{d\phi}{dt},  \frac{dz}{dt} \f$
     !> @author  Routine Author Name and Affiliation.
     !> @param[in] x
     !> @param[out] y
  
     SUBROUTINE h(x,y)
       REAL :: x
       REAL :: y
       y=x**2
     END SUBROUTINE h
  
     !> @brief Brief description of routine.
     !> @details Flow method (rate of change of position) used by integrator.
     !! Compute \f$ \frac{d\lambda}{dt} , \frac{d\phi}{dt},  \frac{dz}{dt} \f$
     !> @author  Routine Author Name and Affiliation.
     !> @param[in] x
     !> @param[out] y
     SUBROUTINE i(x,y)
       REAL :: x
       REAL :: y
       y=x**2
     END SUBROUTINE i
  !> @}
  !> @}
  
  

• You may have noticed that we have another set of curly braces following the @name tag in the above example. In addition to 'module groups' (doxygen modules) you can also group things within the same file in what are called 'member groups'. These (unlike module groups) will show up when viewing the file or the fortran module. Member groups unlike module groups however cannot be nested within other member groups. And objects grouped in member groups must be physically grouped in the actual file. (There is no addtogroup equivalent for member groups.) The member group declaration section that begins with '@name' must be before the group of objects and should end with curly brackets

• Since both member groups use curly brackets as well as module groups some care must be taken when including functions in both types of groups. In fact Doxygen seems to not support putting objects of member groups in different module groups. Module group tags (@defgroup, @addtogroup, @ingroup etc…) should not be placed inside of a member group. This should be possible but the results seem to be unpredictable….

• So why use member groups at all? Member groups unlike module groups show up when viewing fortran modules & files - so in some respect are more preferential to module groups - when they can be used. This however requires the members to be physically grouped in the file - and does not allow for sub-grouping.

• Directories can also be commented using the @dir tag at the start of the main file in the directory

• What in the world to use module groups for? My two cents is to group fortran entities into modules - modules/functions/variables etc.. instead of files and directories (since these are already grouped on the disk). Since functions and variables within a module can be grouped using member groups - fortran modules seem the obvious choice for grouping with module groups. Nesting member groups of functions within module groups may be useful for visualizing in some instances - but it is always preferable to create a member group if the functions are adjacent - before nesting within a module group.