" Все будет правильно, на этом построен мир." - Михаил Булгаков

Sunsys Dox C++ documentation system

  1. Synopsis
  2. Usage
  3. Configuration
  4. Documentation Tags
  5. Inline HTML Tags
  6. Style and Conventions
  7. Known problems
  8. Legal Information

 

1. Synopsis

Sunsys Dox is a postprocessor of XML output produced by the documentation tool Doxygen from C++ source code. The format of the documentation within C++ source code (/** ... */ comment blocks) is similar to Javadoc style.

 

2. Usage

The usage is: dox <command | project>

where command  is one of:

  • -h or --help displays a help message
  • -v or --version displays Dox version

and project is the path to the project directory, e.g. the directory containing DoxConfig.xml configuration file and ./xml/ or ./temp/xml/ subdirectory containing Doxygen generated documentation in XML format that is to be processed.

To create a new project first MKDIR a directory with a name of your choice in ./sunsys-dox/projects/. Copy all the files from ./sunsys-dox/template/ into the newly created directory. Adjust the contents of Doxyfile if necessary (see Doxygen documentation for more info). Edit DoxConfig.xml to specify Dox configuration options if necessary. Build documentation with DoxBuild script (DoxBuild.cmd on NT), build without regeneration of XML with DoxRebuild (DoxRebuild.cmd on NT), clean with DoxClean (DoxClean.cmd on NT).

Use index.html (located in ./sunsys-dox/projects/[YourProjectDir]/) to view the created documentation (placed in ./sunsys-dox/projects/[YourProjectDir]/html/). Change visual style of the documentation by editing ./html/resources/styles.css file or supplying a custom one with the same name.

 

3. Configuration

Sunsys Dox is configured on a per-project basis by specifying the following options in the DoxConfig.xml file:

Option Type Description
tabSpacing number

tabulation characters '\t' in preformatted blocks are replaced with the specified number of spaces, if number <= 0 tabs are kept in HTML code

useSimpleFileNames boolean

when set to True file names for the generated HTML documentation are encoded using a short form, otherwise fully qualified file names are produced

formatHTML boolean

when set to True enables generation of HTML documentation, otherwise no HTML output is produced (formatting still takes place; used in performance tests)

formatPrivate boolean

when set to True all the member constructs declared private are included in the produced documentation, otherwise private constructs are omitted

formatIncludes boolean

when set to True enables generation of "Implemented in" blocks for all the compounds reporting the use of #include "..." header files

formatAutoLinks boolean

when set to True any crossreferencing links within description text are kept intact, otherwise only the names of the link targets are included in documentation

formatAutoBrief1 boolean

when set to True an automatic extraction of brief description (if none is given) takes place from the detailed description, otherwise brief description is imported from XML as-is

formatDescription boolean

when set to True enables generation of description text, otherwise an undocumented skeleton of an API is produced

formatEmptyNamespaces boolean

when set to True all the namespaces within a project are included in the produced documentation, otherwise namespaces with no members are omitted

formatNamespacesSummary boolean

when set to True enforces generation of a summary of all the namespaces within a project on the overview page, otherwise the namespaces summary is omitted

outputInfo boolean

when set to True enables output of information messages to stdout

outputWarnings boolean

when set to True enables output of warning messages to stdout

outputDebugInfo boolean

when set to True enables output of debug messages to stdout

Notes:
1) the algorithm used during extraction of brief description works as follows: the detailed description is parsed until the first '.' or '!' (dot or exclamation characters) which must be immediately followed by a WhiteSpace character. Formatting tags such as @b, @c, @e et al are permitted and produce the expected results. If during the extraction an unsupported tag is encountered, such as i.e. <table>, the extraction is aborted and an ellipsis enclosed in square brackets, [...], is appended to the result.
The above described algorithm correctly handles dots within a middle of a sentence, i.e. "The value of constant @c Pi is approximately 3.14 and defines the ratio of the circumference of a circle to its diameter in Euclidean geometry.", as well as situations where a sentence does not have a syntactically correct termination at all, such as "The following table lists all the available combinations: <table> ... </table>".

A project can specify header, footer and overview text to be included into the produced HTML output. Such text is injected into documentation files as-is and thus must itself be a valid HTML. The text can be specified either inline (i.e. <footer>This is a footer.</footer>) or be read from files (such as <footer>file://filename.txt</footer> to read filename.txt from a file).

Option Type Description
header string

specifies header text prepended to the beginning of every generated HTML page

footer string

specifies footer text appended at the end of every generated HTML page

overview string

specifies overview text included on the front page (just before the list of namespaces)

When header, footer or overview are read from a file, the following options can be used to specify the values of their corresponding keywords which are expanded inline within the produced HTML:

Option Type Keyword Description
N/A string $BUILD$

specifies documentation build date and time (set at run-time)

title string $TITLE$

specifies documentation title

author string $AUTHOR$

specifies the author of the documentation

version string $VERSION$

specifies the version of the documentation

copyright string $COPYRIGHT$

specifies the copyright holder of the documentation

 

4. Documentation Tags

The following documentation tags can be used in C++ comment blocks:

Documentation Tag Alias Meaning
@author  

author tag

@brief  

brief text

@deprecated  

deprecated text (marks enclosing item as deprecated)

@param  

parameter tag

@post  

postcondition tag

@pre  

precondition tag

@remarks @note

remarks/notes tag

@return  

return tag

@see  

see reference tag

@since  

since tag

@throw @exception

throws tag

@version  

version tag

{@link ref label}1  

explicit or external link tag (ref=reference name, label=visible text name)

Notes:
1) All the external link targets are opened in a new, reusable browser window (with HTML target="doxExternFrame").

 

5. Inline HTML Tags

The following HTML tags can be used in C++ comment blocks:

HTML Tag Alias Meaning
<strong></strong> @b, <b></b>

bold text

<em></em> @e, <i></i>

emphasis (italic) text

<code></code> @c, <tt></tt>

typewriter (monotype) text

<sub></sub>  

subscript text

<sup></sup>  

superscript text

<small></small>  

small text

<pre></pre>  

preformatted block

 
<li></li>  

list item (within <ul/ol> block)

<ul></ul>  

start unnumbered list

<ol></ol>  

start ordered list

<hX></hX>  

heading (X designates heading level 1..5)

<a href="..."></a>  

link to an external source

<a name="..."></a>  

anchor

<img src="...">  

image

<hr>  

horizontal ruler

 
<table></table>  

start a table

<tr></tr>  

start a table row (within table tag)

<th></th>  

start a table header (within table row tag)

<td></td>  

start a table cell (within table row tag)

 
&nbsp;  

non-breakable space

<br> @n

line break

 

6. Style and Conventions

The suggested style of documentation and the way of using Documentation Tags is outlined below. All fields are optional and are used wherever appropriate:

/**
 *	@deprecated
 *	Reason for deprecation.
 *
 *	@brief
 *	Brief description.
 *
 *	Detailed description. [note: no @tag]
 *
 *	@param	param1	argument description
 *	@param	param2	another argument description
 *
 *	@return	description of return value
 *
 *	@throw	exception1	exception description
 *	@throw	exception2	another exception description
 *
 *	@pre	Preconditions description.
 *	@post	Postconditions description.
 *
 *	@remarks Special notes and remarks.
 *
 *	@see	reference1, reference2
 *	@see	reference3
 *
 *	@author	Author Name
 *	@version Version number
 *	@since	Since version
 *
 */
Attention!
The order in which Documentation Tags appear in C++ documentation blocks, as well as empty lines between the @tags can be important. The above documentation style is a guideline, however it is the one against which tests are made. Any deviation from the above suggested style may, but is not guaranteed to work correctly!

 

7. Known problems

The code analysis engine implemented within Dox currently does not deduce types of arguments nor return values. This may lead to certain compounds being improperly identified as abstract when, in fact, they are not. Consider the following:

	template <typename Type>
	struct Base
	{
		virtual Type foo() = 0;
	};

	struct Derived:
		public Base<int>
	{
		int foo();
	};

In the above example Derived is a subclass of Base which has an abstract member function foo. Derived implements foo, however Dox is unable to deduce that int is a specialization of Type leading to assumption that the two foo:s are unrelated and hence the Derived is abstract, which of course is incorrect. Such cases can be resolved with typedef:s to ensure that type names syntactically match throughout the compound hierarchy.

 

8. Legal Information

Sunsys Dox is free software; all forms of distribution are permitted provided that no fee is charged for the software.
Doxygen is distributed hereby unmodified, in binary form, under the terms of GNU General Public License.


Sunsys Dox is free software -- NO WARRANTY.
Copyright 2014 by Narech K.
All Rights Reserved.
Sunsys Dox v1.7.2 :: build: 2014-08-29
contact: me go: dox.narechk.net / narechk.net