Instructions On How To Document ROSE

This page specifies how we would like to have ROSE project be documented. There are a lot of different ways to use Doxygen, this page outlines as clearly as possible how this will be done.

Example of Documented Class in IR

An example of how to document a class in ROSE appears at SgInitializedName. A new template is being assembled based on another IR node SgBreakStmt.

• Prefered Doxygen Syntax
  This sections outline which of several different syntax choices to use in documenting ROSE.
  1. Doxygen Comment Specifiers
     Within use of Doxygen please use the / * ! ... * / syntax to specify a comment to be placed into the Doxygen generated documentation.
  2. Comments in Doxygen Input Files
     Comments within the *.docs doxygen inout files are permited and should be specified with // as in the following case:
     ///////////////////////////////////////////////////////////////////////////////
     // Documentation for class SgInitializedName data members
     ///////////////////////////////////////////////////////////////////////////////
     

• Example Codes
  Seperate codes should be provided which show the use of a large enough cross section of ROSE classes. These codes should be specified with the doxygen command. Anchors should be provided separate files which document the example codes. These anchors are to be references in the documentation for each class in ROSE to show both the construction of the class and its use.

• Function Documentation In the documentation of all functions and member functions the function return value and all function parameters should be documented.

• Common Member Functions Many classes contain redefined virtual functions. Use doxygen mechanisms to propogate function descriptions to function descriptions in derived classes.

• Tips
  We have identified several helpful tricks in preparing documentation using Doxygen. Please place additional information to help developers document ROSE consistantly on this page.
  1. Special words to flag different types of documentation that is not finished. These are useful in combination with grep to find remaining unfinished documentation.
     • incomplete-documentation
     • unknown-semantics
     • may-be-removed
     • \deprecated Using the Doxygen deprecated mechanism.
  2. Most directories of the source code contain a *.docs file which contains much of the documentation that is specific to individual classes and which would otherwise clutter the header files. Most of these should already be in place.
  3. Some things we are not currently trying to document using Doxygen:
     • ROSE/src/frontend/EDG
     • Connection of EDG to Sage (contained in ROSE/src/frontend/EDG_SAGE_Connection)
     • ROSE/src/ROSETTA
     • ROSE/src/3rdPartyLibraries/ library (3rd party libraries found on the web)
     • ROSE/ArchitectureSpecificTests

---