Adding a new topic - overview

write a short text file "SomeTopic.markdown" and store it within Folder "DocProductiveCoding" or "DocUnitTesting" which you can find under path C:/UserData/Gerald/MySwArchive/doc/HowToUse
- choose or create a test project with some code samples demonstrating your topic
- add tags at the begin and end of suitable code snippets
- add references to these tags to your markdown file
edit file "MainPage.markdown" and add a reference to your newly added topic
regenerate the documentation using DoxyGen and the "doxyfile"

Add code snippets to documentation

Find and prepare source code

Within your code search for useful snippets which demonstrate aspects of your topic. Mark the found snippets with the same start and end tag "/// [your tag name]". The tags for a single code snippet have to be unique within the source file.

// MySourceFile.cpp
void SomeFunctionWithinRealCode()
{
    // ...
    /// [read node values]
    // Read several child node values according to their expected types
    double x      = selectedNode.child("X")        .text().as_double();
    int numPoints = selectedNode.child("NumPoints").text().as_int();
    bool exists   = selectedNode.child("exists")   .text().as_bool();
    /// [read node values]
    //...
}

Connect markdown file with code snippets

Within your textual description in the markdown file add at least a header and a reference to the code snippet by using "\snippet" and the same corresponding tag name as used within your source code:

// MyTopic.markdown
...
### Read node values as numeric types
\snippet /TestToolBox/Test/TestXmlCheckWithPugiXml/UsingPugiXml.cpp read node values
...

Resulting output within documentation

From markdown files and connected code snippets Doxygen will generate the following html documentation. The generated code sections also support syntax highlighting:

Read node values as numeric types

    // Read several child node values according to their expected types
    double x      = selectedNode.child("X")        .text().as_double();
    int numPoints = selectedNode.child("NumPoints").text().as_int();
    bool exists   = selectedNode.child("exists")   .text().as_bool();

Add selected (header) files to documentation

If you already have well documented (header) files within your source data base then you can simply include them to the generated documentation by defining a corresponding group to which you can put a reference on any place within documentation.

// MyTopic.markdown
...
\defgroup GrpIncludeSourceSomeFileName Header file: MyClassHeader.h
@{
\ingroup GrpSomeParentGroup
\include "SomeDirBelowExamplePath/MyClassHeader.h"
@}
...
// within some other group / page:
For definition of MyClass see \ref GrpIncludeSourceSomeFileName
...

Embedding your topic into document structure

Your topic specific markdown file

Within your markdown file define at least one DoxGen group whithin which you place all your descriptions. At the beginning of the file specify your name and list all contained groups:

// MyTopic.markdown
\author Gerald Fahrnholz
− \ref GrpMyTopic
− \ref ... optionally more groups
 
\defgroup GrpMyTopic This is the title for my topic
@{
   ... [here are your descriptions]
@}

MainPage file

Within the MainPage markdown file choose a suitable location and add a reference to your new topic. The title of your topic will automatically be inserted.

// MainPage.markdown
...
− \ref GrpMyTopic
...

Generating documentation

Before generating the documentation via the DoxyWizard you have to ensure that the path settings within the doxyfile are matching with your environment. Especially the following path settings have to be checked or adjusted:

// doxyfile
 
// where to generate the documentation
OUTPUT_DIRECTORY = C:/MyTEMP/DocGenerated/HowToUse
 
// from where to fetch your code snippets (base path)
EXAMPLE_PATH = ../../C
 
// from where to fetch images (base path)
IMAGE_PATH = C:/UserData/Gerald/MySwArchive/doc/HowToUse