Documenting Source Code

From Gyrokinetics
Jump to: navigation, search

Documenting Source Code has changed - we are now using doxygen.


Documentation of GS2 uses doxygen, one of the most popular tools for automated generation of source code documentation. Essentially, all modules and public module members such as subroutines, functions, types and variables can be documented by placing a special comment above the code which implements that element. All of the comments should begin with "!>" and each new line in the comment should be continued with "!!".

There are some minor flaws. In particular, if you want a type to be properly documented, you need to place it above the private keyword.

Here is an example of a documented module:

   !> This module is a very important
   !! module
   module my_module
     public my_type
     public my_variable
     public my_subroutine
     !> This a type which defines an
     !! object which does useful things
     type my_type
       !> This is a member of my type
       integer :: my_integer
     end type my_type
     !> This is a public variable
     real :: my_variable
         !> This is a jolly good subroutine
         subroutine my_subroutine
   ... etc