View Issue Details

IDProjectCategoryView StatusLast Update
0000103ascenddocumentationpublic2009-05-26 18:21
Reporterjohn 
Assigned Tojohn 
PrioritynormalSeverityminorReproducibilityalways
Status resolvedResolutionfixed 
Product Version 
Target Version0.9.7Fixed in Version 
Summary0000103: doxygen markup of in-source documentation comments
DescriptionFrom the Wiki:

https://pse.cheme.cmu.edu/wiki/view/Project/DocumentingAscend

Documenting ASCEND

Objective

The ASCEND code base contains extensive documentation written by the various developers over time. Currently this documentation is only available by browsing the individual source files with an editor. This valuable resource could be even more useful in formatted, linked format. The doxygen (http://www.stack.nl/~dimitri/doxygen/) documentation system provides a natural way to compile in-source documentation into a such a formatted manual.

Use of doxygen requires that the comments be in a standardized, coded format. The objectives of this effort are to:

    * convert the existing comments into doxygen format
    * establish a standard comment format for use in new code
    * extend documentation to the implementation as appropriate (currently, only the interfaces in headers are extensively documented)

Status

26-Dec-2004
BenAllan? completed initial conversion of comments using sed. Committed as revision 43.

02-Aug-2005
JerryStClair completed initial manual rework of doxygen comments in all headers. Committed as revision 71. Modifications included:

    * Added @file comment to all headers.
    * Added parameter names to all function declarations in headers.
    * Corrected comment referencing where necessary.
    * Split some comments which documented blocks of declarations.
    * Converted notes about required work into @todo comments so doxygen can generate a todo list.

30-Aug-2005
The following still needs to be done to complete the header documentation conversion:

    * complete documentation of undocumented modules (see doxygen todo list)
    * clean up redundant comments left in place during initial rework
          o remove original comments if new ones are acceptable
          o remove commented-out parameter and return value specifications (redundant with full function prototypes now in place)
TagsNo tags attached.

Relationships

Activities

john

2005-10-28 07:38

administrator   ~0000013

Last edited: 2005-11-04 08:57

Any chance of a hosted version of the resulting dox? Ideally, you could set up a quick cron job to check out your sources and run doxygen on them, then stick them on this server somewhere?

john

2009-05-26 18:21

administrator   ~0000552

Added cron job to perform doxygen processing of trunk each night.

Issue History

Date Modified Username Field Change
2005-10-28 07:38 john New Issue
2005-10-28 07:38 john Note Added: 0000013
2005-11-04 08:57 john Note Edited: 0000013
2006-02-07 13:19 john Target release => 1.0
2006-02-07 13:23 john Target release 1.0 => 0.9.6
2006-05-10 03:50 john Target release 0.9.6 => 1.0
2008-02-10 17:59 john Status new => assigned
2008-02-10 17:59 john Assigned To => john
2009-05-01 16:52 john Target Version => 0.9.7
2009-05-01 17:58 john Target Version 0.9.7 => 1.0
2009-05-01 18:03 john Target Version 1.0 => 0.9.7
2009-05-26 18:21 john Note Added: 0000552
2009-05-26 18:21 john Status assigned => resolved
2009-05-26 18:21 john Resolution open => fixed