Documentation of the code

[PetrS]

Documentation of the code

In SDF you can create documentation for your code by including XML elements in special comment fields (indicated by triple slashes) in the source code directly before the code block to which the comments refer, for example:

Code: Select all

/// <summary>
/// Description of the function
/// <summary>
/// <param name="A">Description of parameter A</param>
/// <param name="B">Description of parameter B</param>
/// <param name="C">Description of parameter C</param>
/// <param name="D">Description of parameter D</param>
/// <returns>Description of function return value</returns>
double TestFunction(double A, string B, object C, bool D) {
    return 0;
}


These XML elements are used to automatically generate HTML documentation by DesignForms_DocGenerator.

List of supported elements:

• <summary>
• <param>
• <returns>
• <code>
• <seealso>
• <example>
• <list>
• <item>

[PetrS]

Using DesignForms_DocGenerator

Run bDesignForms_DocGenerator.exe/b from command line.
DocGenerator will find all CLS files in given directory (including sub-directories) and generate HTML documentation based on XML-tags in the code.

Command line parameters:

• -SOURCEDIR:"<directory_with_cls_files>"
• -OUTPUTDIR:"<directory_for_generated_output>"
• -PAUSE:1 - optional parameter which keeps console window visible at the end of export

Examples:
code
DesignForms_DocGenerator.exe -SOURCEDIR:"d:\OpenChecks\Forms" -OUTPUTDIR:"d:\Documentation"
DesignForms_DocGenerator.exe -SOURCEDIR:"d:\OpenChecks\Forms" -OUTPUTDIR:"d:\Documentation" -PAUSE:1
/code

Notes:

• DocGenerator ignore classes and functions WITHOUT public modifier. PUBLIC must be explicitly set to get documentation of the function/class.
• Structure of the source directory is used to generate structure of namespaces = structure of the documentation

[jkrsik]

Example of using two level list


Real life example of using documentation of code with two level list.
Example is one of functions from Concrete\Functions1D_geometrics.cls

Code: Select all

/// <summary>
/// Function for determination if some line has intersection with edge of css
/// <summary>
/// <param name="AngleLineLoad">Angle of loaded line in degrees</param>
/// <param name="CssID">ID of used cross-section</param>
/// <param name="IndexEdge">Index of edge for calculation</param>
/// <returns>Returns structured array:
/// <list type="bullet">
///   <item>"Type"
///     <list type="bullet">
///       <item>-1 - outside</item>
///       <item>0 - inside</item>
///       <item>1 - first point</item>
///       <item>2 -  second point</item>
///     </list>
///   </item>
///   <item>"X" - X coordinate of intersection</item>
///   <item>"Y" - Y coordinate of intersection</item>
/// </list>
/// </returns>
/// <code>
/// IF () {
/// } ELSE {
/// }
/// </code>
/// <example>http://designforms.net/forum</example>


Result of code above after doxygen generation:
attachment=0CodeDocumentationExample.PNG/attachment