Difference between revisions of "Doxygen"

From Octave
Jump to navigation Jump to search
(use octave.org links and link to stable and dev)
(Added information about the preferred style used in Doxygen)
Line 24: Line 24:
  
 
Very little Doxygen documentation is currently available in Octave's source code. Which is why "Doxygen documentation for the C++ classes" is listed in the [http://wiki.octave.org/Projects#Documentation_and_On-Line_Help Projects] page of this wiki.
 
Very little Doxygen documentation is currently available in Octave's source code. Which is why "Doxygen documentation for the C++ classes" is listed in the [http://wiki.octave.org/Projects#Documentation_and_On-Line_Help Projects] page of this wiki.
 +
 +
==== Doxygen Style Guide ====
 +
 +
Doxygen allows for a variety of commenting styles. In order to maintain uniformity across the entire project the following rules should be applied:
 +
 +
* For short Doxygen comments use {{codeline|//!}}
 +
* For longer comments use {{codeline|/*! ... */}}
 +
* For longer comments do not add {{codeline|*}} before each line
 +
* Use {{codeline|@}} for any Doxygen Special Commands
 +
 +
An example  of properly used Doxygen would look like:
 +
 +
<pre>
 +
//! Short Comment.
 +
/*!
 +
    Longer comment with special command and syntax highlighting:
 +
 +
    @code{.cc}
 +
    double v = 1.0;
 +
    @endcode
 +
*/
 +
</pre>
 +
 +
For actual use example look at [http://hg.savannah.gnu.org/hgweb/octave/file/1327ea4f5a93/liboctave/array/Array.h#l46 liboctave/array/Array.h]
 +
  
 
[[Category:Development]]
 
[[Category:Development]]

Revision as of 10:03, 21 September 2017

What is Doxygen ?

Doxygen is the de facto standard tool for generating documentation from annotated C++ sources [1]

Generating the Doxygen documentation for Octave

Doxygen documentation for Octave is easily generated from Octave sources. Instructions can be found in doc/doxyhtml/README.

Where can I browse the Doxygen documentation for Octave ?

Alternatively, you can access version specific Doxygen documentation:

What is the current status of Octave's Doxygen documentation ?

Very little Doxygen documentation is currently available in Octave's source code. Which is why "Doxygen documentation for the C++ classes" is listed in the Projects page of this wiki.

Doxygen Style Guide

Doxygen allows for a variety of commenting styles. In order to maintain uniformity across the entire project the following rules should be applied:

  • For short Doxygen comments use //!
  • For longer comments use /*! ... */
  • For longer comments do not add * before each line
  • Use @ for any Doxygen Special Commands

An example of properly used Doxygen would look like:

//! Short Comment.
/*!
    Longer comment with special command and syntax highlighting:

    @code{.cc}
    double v = 1.0;
    @endcode
*/

For actual use example look at liboctave/array/Array.h