DE AutoDoc - Part I   Markup Documentation

Contents

  1. Overview
  2. Description of Markup Tags
    1. Special Features
    2. File Tags
    3. Structure Tags
    4. Functional Tags
    5. Sub Tags
      1. Source Code Quoting
      2. Include AutoDoc Markup from a File
    6. Inline Tags
    7. Definition of Groups
    8. Multi file languages, like C and C++
    9. Bibliography and Reference Functionality
    10. Examples
      1. File Description Examples
      2. Structure Description Examples
      3. Functional Descriptions Examples
    11. Index of all Tags

 


Overview

The idea of the automatic documentation is to markup program source code with special comments in order to create the technical documentation automatically using these special comments from the source code.

The markup takes place in special comment blocks. The default block markers for the individual programming languages are defined in the file extensions defaults file res/AutoDocFileExtensionDefaults.txt. If the file extensions used is not find there, the default for such block start is "/*!" and for a block end is "*/". These markers can be used with any programming languages, which has block comment delimiters "/*" and "*/", like C, C++, Java, JavaScript, SAS, CSS, etc. For other programming languages.

Other block identifiers can be defined by the -extdef command line parameter.

A simple example markup block comment may look as follows:

/*!
Put markup information  here.
*/

Inside the block, certain markup tags can be defined. All the supported tags are defined here in this documentation. Additionally, the markup blocks can be bordered using an "*", to have a nicer look in the source code of the program, e.g.:

/*!********************************
*  Put markup information  here.  *
**********************************/

As characters to build the border only characters appearing in the block markers can be used or an "*" can be used to draw the border. The border must be build in such a way, that the programming language still threats the whole block as a comment.

You can also use a single border on the left side. In the following example

/*!********************************
*  Put markup information  here.
   Second line                    *
**********************************/

the first line has a border on the left side which is correct, but the second line would be illegal, because it has only a border on the right side.

There are five types of tags, which AutoDoc understands:

Each markup tag has it's individual numbers of parameters. If a certain tag has more than one parameter and one of the parameter contains white space characters (like blank, tab, newline), AutoDoc may not split the parameters correctly. For example the "@history" tag expects 4 parameters. In the follwing example

...
* @history     DATE       VERS   AUTHOR          DESCRIPTION
* @history     23.04.2015  1.0   Daniel Enache   Initial implementation.
...

the author contains a blank between "Daniel" and "Enache". AutoDoc would expect, that "Enache" is not part of the author, but of the description parameter. To prevent such unintended splits, parameters can be enclosed in quotes, like in the following example:

...
* @history     DATE       VERS   AUTHOR            DESCRIPTION
* @history     23.04.2015  1.0   "Daniel Enache"   Initial implementation.
...

Now, the correctly rendered output is generated. The following example would wourk for almost all programming languages. One exception would be Smalltalk, because the double quote is the comment character in this programming language. For Smalltalk, single quotes must be used, like in the following example.

...
* @history     DATE       VERS   AUTHOR            DESCRIPTION
* @history     23.04.2015  1.0   'Daniel Enache'   Initial implementation.
...

For a list of supported programming languages and their quoting character, see the description of the Extension Defaults.

However, it could happen, that it is intended that quotes should appear in the output. If that happens, one can force them appearing by the inline tags {@q} (single quote) and {@qq} (double quote), as in the following example:

...
* @history     DATE       VERS   AUTHOR            DESCRIPTION
* @history     23.04.2015  1.0   "Daniel Enache"   Initial {\qq}implementation{\qq}.
...

Here, the word "implementation" appears in double quotes in the output.

 

Description of Markup Tags

A AutoDoc tag always begins with the tag character @ and followed by the tag name and additional parameters delimited by spaces, tabs, line breakes (white space). In the exaples in this documentation, we always used @ as tag character, although it is possible to use the alternative tag character \. The tag character is automatically detected for each file from the two characters @ and \, depending, which one is used in the first tag in the file.

For example to mark up a program, you can use the "@program" as follows:

/*!*******************************************
*  @program  This program does nice things.
*********************************************/

The "@program" tag is a File Tag and requires only one parameter: the file description. In this example, the file is marked as a program and description "This program does nice things.".

The program tag only requires one parameter. As you can see below, there are tags, which require more than one parameter. The last parameter is always the parameter called Description.

The Description need not to be quoted and may contain spaces, line breaks and other delimiters. This is different for all other parameters. If they contain white space characters, they must be quoted by the quoting character defined in the File Extension Defaults file. For almost all programming languages, the quote character is ". But for example, Smalltalk uses this character as a comment caharacter, so for Smalltalk the single quote ' is defined as quoting character. In the following sections we will see examples for quoted parameters.

 

Special Features

In the description part of every markup tag, there are certain transformations performed, that helps formatting and structuring of the output. Example:

Paragraphs: Empty lines within a description are translated into a new paragraph.

/*!*******************************************
*  @program This program does nice things. 
*                                          
*    This is a new paragraph.              
*********************************************/

 

Numbered item lists: If at least two sub sequent lines within a description start with a number followed by a dot, the list is translated into a numbered list (HTML <ol>). The list is either finished by a new tag or be an empty line. E.g.:

/*!*******************************************
* @program This program does nice things.
*                                        
*    To install the program:            
*    1. Create a directory. 
*    2. Copy files into directory. 
*                                  
*   That's it.     
*********************************************/

 

Unnumbered item lists: If at least two sub sequent lines within a description start with "-" followed by white space, the list is translated into a unnumbered list (HTML <ul>). The list is either finished by a new tag or be an empty line. E.g.:

/*!*******************************************
* @program This program does nice things.
*                                        
*    To install the program:             
*    - Create a directory.               
*    - Copy files into directory.        
*                                        
*   That's it.                           
*********************************************/

 

File Tags

These type of Tags are containing information about the file, the file type, the file name, and a description of the file. They can only appear once in a file and are mandatory. If more than one is provided, the first encountered is taken. The following Tags are supported and expect all only 1 parameter:

TagDescriptionNo. Param.Syntax
@excludeMarks the file to be excluded from documentation.1@exclude Description
@fileDefines the file as a general file.1@file Description
@libraryDefines the file as a library.1@library Description
@programDefines the file as a program.1@program Description
@subprogramDefines the file as a sub program which is part of a bigger program.1@subprogram Description

The @exclude tag is interesting, because it enables the user to exclude certain files from the dicumentation. For example, old program versions can be marked like this to avoid duplicated documentation.

Example:

/*!*********************************************
* @library This library contains utilities.
*                                          
*    Second <b>paragraph</b>.  
***********************************************/

As you can see in the last example, a paragraph can be added to the description by an empty line within the block and also HTML tags can be used in the description. The output may look like in the following screenshot:

 

Structure Tags

The Struncture Tags are optional. They assist in showing up the structure of the program, which is especially interesting for very huge programs. The following Tags are supported and expect all 2 parameters:

TagDescriptionNo. Param.Syntax
@classMarks the beginning of a class.2@class Classname Description
@includesDescribes included files.2@includes Filename Description
@interfaceMarks the beginning of an interface.2@interface Interfacename Description
@progsectionMarks the beginning of a logical section.1@progsection Description
@stepDescribes a step (e.g. a SAS step or proc).1@step Stepname Description

The tag @class is only applicable to object oriented programs.

Example:

/*!******************************************************
* @progsection Initialization 
********************************************************/

/*! @includes "Utils.sas"      Utility library. */

In this example first the program section "Initialization" is marked and then the inclusion of the "Utility library" is declared. The output will look like this:

In the last example, the first parameter Utils.sas does not contain any spaces, so the quotes are optional.

The descrition part may be omitted, as in the following example.

/*! @includes "Utils.sas" */

Since version 1.2, the description is taken from the included file, if it is part of the input files and contains AutoDoc markup.

 

Functional Tags

Functional tags are used to markup functions, methods, macros, etc. The follwoing tags are supported by AutoDoc and all have 2 parameters:

TagDescriptionNo. Param.Syntax
@fieldDescribes a class field.2@field Fieldname Description
@formatDescribes a format definition.2@format Formatname Description
@functionDescribes a function.2@function Functionname Description
@macroDescribes a macro.2@macro Macroname Description
@methodDescribes a class method.2@method Methodname Description
@procedureDescribes a procedure.2@procedure Functionname Description
@saslibnameDescribes a SAS local libname.3@saslibname Name Definition Description
@sasrlibnameDescribes a SAS remote libname.3@sasrlibname Name Definition Description
@variableDescribes a variable.2@variable Variablename Description

For function, method or macro names only the name must be supplied, for example

/*!******************************************************
* @macro getRowsOfTable         
*     Gets the rows of a table. 
********************************************************/

but it is strongly advised to include all of the parameters of the call, because it will make the documantation more readable:

/*!******************************************************
* @macro "getRowsOfTable(tablename, libname)"
*     Gets the rows of a table.              
********************************************************/

Note, that the name must be quoted, if it contains white space characters. The output will look like this:

 

Sub Tags

Sub tags can be used to provide additional information for all the tags presented above. The following sub tags are available in AutoDoc:

TagDescriptionNo. Param.Syntax
@attentionAdds attention information.1@attention Description
@authorAdds author information.1@author Authorname
@beginsrcquoteMarks that subsequent code up to is quoted endsrcquote in the output.0@beginsrcquote
@bibAdds a global bibliography reference.2@bib UniqueID Bibliography Entry
@biblAdds a local bibliography reference.2@bibl UniqueID Bibliography Entry
@briefAdds brief description (for DoxygenTM compatibility only).1@brief Description
@bugAdds bug information.1@bug Description
@callsAdds function, method, or macro which is called. Experimental.1@calls RoutineName
@changesAdds information about changes.1@changes Changes information
@chgreasonAdds information about change reasons.1@chgreason Change reason information
@classificationAdds classification information.1@classification Classification information
@clientAdds client information.1@client Clientname
@commentSuppresses output of the following parameter.1@comment Suppressed
@companyAdds company information.1@company Company information
@contactAdds contact information.1@contact Contactinfo
@copyrightAdds copyright information.1@copyright Description
@dateAdds date information.1@date Date
@departmentAdds deparment information.1@department Deparment information
@deprecatedMarks the parent tag as deprecated.1@deprecated Description
@detailsAdds detailed description (for DoxygenTM compatibility only).1@details Description
@directoryAdds directory information.2@directory Directory-Name Directory
@docuAdds documentation information.1@docu Description
@durationAdds information about the duration of the program run.1@duration Description
@endsrcquoteMarks that code since beginsrcquote is quoted in the output.0@endsrcquote
@exampleAdds an example.1@example Description
@extendsAdds information about the parent class.1@extends Description
@freqAdds information about the excecution frequency of the program.1@freq Description
@groupAdds group information.1@group Groupname
@hiddengroupAdds group information.1@hiddengroup Groupname
@historyAdds history log information.4@history Version Date Author Description
@howtoAdds usage information.1@howto Description
@implementsAdds information about the implemented interface.1@implements Description
@includeadIncludes AutoDoc markup from a file.1@includead Filename
@inputDescribes input data.2@input InputName Description
@licenceDescribes the underlying software licence.1@licence Description
@moduleAdds module information.1@module Namespace name
@namespaceAdds namespace information.1@namespace Namespace name
@noteAdds a note.1@note Description
@outfileAdds output file information1@outfile Description
@outpathAdds output path information1@outpath Description
@outputDescribes output data.2@output OutputName Description
@packageAdds package information.1@package Package name
@paramAdds information about a parameter.2@param Name Description
@permissionAdds permission information.1@permission Permission information
@postcondAdds post-condition information.1@postcond Description
@precondAdds pre-condition information.1@precond Description
@returnAdds information about the return value.1@return Description
@requestorAdds requestor information.1@requestor Requestorname
@reviewerAdds reviewer information.1@reviewer Name
@sectionAdds information of a user defined section.1@section Section-Heading Description
@seeAdds a cross reference description.1@see Reference Description
@sinceAdds minimum compiler / interpeter version.1@since Version
@statusAdds status information.1@status Status-Information
@testdocAdds test documentation information.1@testdoc Test documentation
@testerAdds tester information.1@tester Name
@throwsDeclares a thrown exception.1@throws Exceptionname
@todoAdds TODO information.1@todo Description
@userAdds user information.1@user Authorname
@versionAdds version information.1@version Version
@warningAdds warning information.1@warning Description

For exaple, a typical file descrpition header with sub tags could look as follows:

/*!**************************************************************************** 
* @program  Main program for the Astrology software.                   
*                                                                      
*           Here is some more detailed information.                    
* @version  1.1                                                        
* @since    Java 1.4                                                    
*                                                                      
* @group    types/software                                             
* @group    types/software/astro                                       
* @group    users/denache                                              
*                                                                      
* @author   Daniel Enache                                              
* @author   Enache Daniel                                              
* @date     29.03.2014                                                 
* @contact  denache@gmx.de                                             
* @contact  denache67@gmail.com                                        
*                                                                      
* @warning  This is a test warning.                                    
*                                                                      
* @howto    1. Install the program.                                    
*           2. Run the program.                                        
*                                                                      
* @input    data/ClientData.csv       Example client data.             
* @input    data/Coordinates.csv      Geo coordinates database.        
* @input    data/CountryCodes.csv     Country codes table.             
* @input    data/TimezoneCountry.csv  Timezone Country matching table. 
*                                                                      
* @output   userdata/ClientData.csv   Users client data.               
* @output   userdata/CurClient.csv    Users current client.            
*                                                                      
* @todo     There is still stuff to do.                                
*                                                                      
* @history  VERS    DATE        AUTHOR      DESCRIPTION                
* @history  1.0     01.01.2013  "DE"          Initial implementation.
* @history  1.1     29.03.2014  "DE"          Some corrections.      
******************************************************************************/ 

This will create the following output:

Note, that the @history tag has 4 parameters. The order in which the parameters Version Date Author Description are to be entered is only a recommendation and can be changed. It is only strongly recommended, that the Description parameter is the last parameter to avoid having to quote it. In this example also a heading is created with the same tag.

And a typical functional header would be:

/*!****************************************************************************  
* @method "public double calcDescendatAngleFromAscendant1(double dAscendant, int type)" 
*         Calculated the angle of the descendant from an already  
*         calculated ascendant.                                   
* @param  dAscendant  Ascendant angle in degrees.                 
* @param  Type        Type of calculation.                        
* @return Descendant angle in degrees.                            
******************************************************************************/ 

Creating the following output

The @group tag is a very special tag. It enables to define hierachical groups to be shown in the frames or treeframes output. For more datails on this feature see the section "Definition of Groups".

 

Source Code Quoting

Usually, when you try to quote source code of the program, you can use the Inline-Tag @code within any description text. See section Inline Tags for details. To accomplish this, you have to include the whole source code you want to quote as parameter to the Inline-Tag. The disadvantage is that each time you change the program code, you also have to update the quoted code.

Since AutoDoc version 1.1.1, it is possible to mark the beginning and end of the program code to be quoted by the Sub-Tags @beginsrcquote and @beginsrcquote. For example:

/*!***************************************************************************
* @progsection Update batch status table. 
******************************************************************************/ 
/*! @beginsrcquote */
data Status;
   set Status;
   x = y; /* Update */
run;
/*! @endsrcquote */

The source code is inserted at the position of @beginsrcquote. So, in the next example

/*!***************************************************************************
* @progsection Update batch status table. 
* @beginsrcquote
* @note This is the note.
******************************************************************************/ 
data Status;
   set Status;
   x = y; /* Update */
run;
/*! @endsrcquote */

it is inserted before the Note information.

Please note, that the quoted source code must not contain any AutoDoc Markup.

 

Include AutoDoc Markup from a File

Since AutoDoc version 2.1.10 it is possible to include AutoDoc markup from an external file. It enables to store common markup blocks to be used in more than one file in order to reduce redundancy.

The markup in the file should have the following properties:

For example, we have an external file "Authors.inc" containing the following markup:

@author    Daniel Enache               
@client    Myself                          

Then, we can simply include it into the AutoDoc markup ("C++\main.cpp") like this:

/*!************************************************************************** 
* @program    Test program for MyClass.   
*                                         
* @includead  ..\Authors.inc
* @namespace  std                         
****************************************************************************/ 

Please note, that relative paths are used, the path of the file to be included is always relative to the current file location being processed. In this case AutoDoc searches for the file "Authors.inc" in the parent directory of "C++".

The extension of the included file does not have to be ".inc" as in the example. It could have any extension. Just make sure it is not processed by AutoDoc directly, by either placing it outside the chosen input directories or setting the -ext or -exclude parameters accordingly. Otherwise it would produce warning messages ("The file XXX doen not contain any tags.").

The result is the same, as if the file ("C++\main.cpp") did contain the following:

/*!************************************************************************** 
* @program    Test program for MyClass.   
*                                         
* @author     Daniel Enache               
* @client     Myself                          
* @namespace  std                         
****************************************************************************/ 

 

Inline Tags

Inline Tags can be used in other tags in description parts. Inline tags must be quoted by curly braces { and } and cannot be nested. The following inline tags are supported:

TagDescriptionNo. Param.Syntax
@bSets the text in bold font.1{@b Text}
@biSets the text in bold italic font.1{@bi Text}
@bisSets the text in bold italic strike-through font.1{@bis Text}
@biuSets the text in bold italic underlined font.1{@biu Text}
@bsSets the text in bold strike-through font.1{@bs Text}
@buSets the text in bold underlined font.1{@bu Text}
@citeAdds a reference to a bib item.1{@cite UniqueID}
@codeAdds source code.1{@code Codefragment}
@emSets the text in emphasized font.1{@em Text}
@esSets the text in emphasized strike-through font.1{@es Text}
@euSets the text in emphasized underlined font.1{@eu Text}
@extlinkAdds an external link to another document.2{@extlink URL Label}
@iSets the text in italic font.1{@i Text}
@imgAdds an image.2{@img Image-File Vertical-Orientation}
@newlineInserts a new line.0{@newline}
@linkAdds an internal link to another document.2{@link URL Label}
@qInserts a single quote character '.0{@q}
@qqInserts a double quote character ".0{@qq}
@sSets the text in strike-through font.1{@s Text}
@ttSets the text in typewriter font.1{@tt Text}
@ttbSets the text in typewriter bold font.1{@ttb Text}
@ttbiSets the text in typewriter bold italic font.1{@ttbi Text}
@ttbisSets the text in typewriter bold italic strike-through font.1{@ttbis Text}
@ttbiuSets the text in typewriter bold italic underlined font.1{@ttbiu Text}
@ttbsSets the text in typewriter bold strike-through font.1{@ttbs Text}
@ttbuSets the text in typewriter bold underlined font.1{@ttbu Text}
@ttiSets the text in typewriter italic font.1{@tti Text}
@ttisSets the text in typewriter italic strike-through font.1{@ttis Text}
@ttiuSets the text in typewriter italic underlined font.1{@ttiu Text}
@ttsSets the text in typewriter strike-through font.1{@tts Text}
@ttuSets the text in typewriter underlined font.1{@ttu Text}
@uSets the text in underlined font.1{@u Text}

For HTML output, any picture file type valid for HTML can be used for the {@img} tag, e.g. *.jpg, *.gif, *.png. However, the file formats which can be uesd for LaTeX may differ depending on the LaTeX implementation. For mikTeX for example, both latex and pdflatex options work with *.jpg and *.gif is not supported.

An example for the @code tag could be:

/*!****************************************************************************  
* @method "public double calcDescendatAngleFromAscendant(double dAscendant, int type)"
*         Calculated the angle of the descendant from an already         
*         calculated ascendant.                                          
*                                                                        
* Use as follows: {@code                                                  
*                  double dRes = calcDescendatAngleFromAscendant(x, 0);  
*                  ...                                                   
*                  System.out.println(dRes);                             
*                  }                                                     
*                                                                        
* @param  dAscendant  Ascendant angle in degrees.                        
* @param  Type        Type of calculation.                               
* @return Descendant angle in degrees.                                   
******************************************************************************/ 

creating the following output

If the @code tag is more than one line, as in the previous example, AutoDoc assumes, that it is a block of code and produced an according output. Here, also indentation is possible. If the @code is within the text of a single line, AutoDoc assumes, that the code should be displayed within the current line and not in a separate block.

With the @extlink tag you can add external links to your document. This is an example:

/*!****************************************************************************
* @program  Main program for the Astrology software.                      
*                                                                         
*           Here is some more detailed information.                       
*           For further information see the following                     
*           {@extlink http://www.enache.de Web page}. You may also want   
*           to look at {@extlink http://www.google.com}.                  
* @version  1.1                                                           
* @since    Java 1.4                                                       
*                                                                         
******************************************************************************/ 

creating the following output

The @link tag is used for cross references within the documentation generated by AutoDoc. a link has the general form File#Marker.

If you just want to make a reference to a file, you can use for example:

/*!****************************************************************************
* @program  Main program for the Astrology software.   
*                                                      
*           Here is some more detailed information.    
*           For further information see the following  
*           {@link AstroCalc.java# Description}.       
* @version  1.1                                        
* @since    Java 1.4                                    
*                                                      
******************************************************************************/ 

In this example, the marker part of the reference is empty, because we only want to refer to the file. The # at the end is important here to indicate, that this is a file reference. If we would leave it out, like in this example:

/*!****************************************************************************  
* @program  Main program for the Astrology software.    
*                                                       
*           Here is some more detailed information.     
*           For further information see the following   
*           {@link AstroCalc.java Description}.         
* @version  1.1                                         
* @since    Java 1.4                                      
*                                                       
******************************************************************************/ 

Autodoc will assume, that it is a refence within the current file and would search the marker "AstroCalc.java" in the current file.

As you seen in the example the marker indicates the object within the file. Currently only functinal tags are supported as markers. The marker consists of an optional class name, the function or method name, and all parameters, as described in the corresponding @function, @method, or @macro tags. The syntax is:

[classname.]funcname[(parameters)]

For example:

/*!****************************************************************************
* @program  Main program for the Astrology software.     
*                                                        
*           Here is some more detailed information.      
*           For further information see the following    
*           {@link "AstroCalc.java#AstroCalc.calcDescendatAngleFromAscendant(double dAscendant, int type)" Description}.
* @version  1.1        
* @since    Java 1.4     
*                      
******************************************************************************/ 

would refer to the "calcDescendatAngleFromAscendant" method of the class "AstroCalc" in the file "AstroCalc.java". Note, that qualifiers and return types which come before the method name (public, static, int, etc.) are omitted here in order to have shorter links for cross references. And

/*!****************************************************************************  
* @program  Main program for the Astrology software.                
*                                                                   
*           Here is some more detailed information.                 
*           For further information see the following               
*           {@link "AstroMain_New2.main(String args)" Description}. 
* @version  1.1                                                     
* @since    Java 1.4                                                  
*                                                                   
******************************************************************************/ 

to the "main" method in the current file ("AstroMain_New2.java")

Note, that the first parameter cointains spaces, therefore it is quoted within ". Another example is:

/*!***************************************************************************/  
* @program  Main program for the Astrology software.   
*                                                      
*           Here is some more detailed information.    
*           For further information see the following  
*           {@link "AstroCalc.java#AstroCalc.calcDescendatAngleFromAscendant(double dAscendant, int type)" Description}. 
* @version  1.1       
* @since    Java 1.4   
*                     
******************************************************************************/ 

If you want the cross references to be separated from your general description, you may use the @see tag, as in this example:

/*!****************************************************************************  
* @program  Main program for the Astrology software.  
*                                                     
*           Here is some more detailed information.   
* @version  1.1                                       
* @since    Java 1.4                                   
* @see      For further information see the following 
*           {@link "AstroCalc.java#public double calcDescendatAngleFromAscendant(double dAscendant, int type)" Description}.
*  
******************************************************************************/ 

 

The @img tag adds an image to the documentation. The first parameter is the filename of the image file, either absolute or relative to the current file. The second parameter is the vertical orientation. Allowed values are "block", "top", "center", or "bottom". When "block" is specified, the image is displayed in a separate line / block. This is also the default, if the secon paraemter is omitted. In all other cases the image is displayed inline.

 

Defintion of Groups

As mentioned previously, using the @groups tag, it is possible to define groups, which are shown in the frames and treeframes output in the left frame. With this feature it is possible to give more structure to the files, especially if your project has a lot of files.

You can either define simple groups, like in the following example:

/*!**************************************************************************** 
* @program  Main program for the Astrology software.                    
*                                                                       
*           Here is some more detailed information.                     
*           For further information see the following                   
*           {@extlink http://www.enache.de Web page}. You may also want 
*           to look at {@extlink http://www.google.com}.                
* @group    Java                                                        
* @group    Astrology                                                   
*                                                                       
******************************************************************************/ 

Here the program "AstroMain.java" is marked as belonging to the group "Java" and to the group "Astrology". But if your documentation project has a really huge amount of files, it might be more convenient to use hierarchical groups, as in the following example.

/*!**************************************************************************** 
* @program  Main program for the Astrology software.                    
*                                                                       
*           Here is some more detailed information.                     
*           For further information see the following                   
*           {@extlink http://www.enache.de Web page}. You may also want 
*           to look at {@extlink http://www.google.com}.                
* @group    types/software                                              
* @group    types/software/astro                                        
* @group    users/denache                                               
*                                                                       
******************************************************************************/ 

As you see, the hierarchy is simply achieved by separating the levels by "/". The example will produce the following output in the left window of the treeframes output.

The groups are usually listed in the individual documentation file and, if a tree view is generated in the tree view index on the left side of the output.

However, if you want to supress the group information in the individual files and only want to keep them in the tree view, you can use the "@hiddengroup" tag instead of the "@group" tag.

The approach specifiying a group bey entries separated by "/" has the advantage that it is easy to use. Every user can easily define hierarchical groups. The drawback of this approach is, that if a group of users want to have standardized groups, simple typing errors can easily mess up the standardized group hierarchy.

Therefore, a second approach can be used, to implement standardized groups. These standardized groups are stored in the AutoDocUserGroupDefs.txt in the AutoDoc's res sub-directory. It is not recommended to modify the AutoDoc setting files directly. Rather make a copy of the res directory and modify that copy. Then point the "-res" parameter to this modified directory.

For example, if you want to define a user defined standardized group "DENACHE" which should generate the group entry "users/denache", you could add the following entry to the AutoDocUserGroupDefs.txt file:

"DENACHE", "users/denache"

To used these standardized user groups you can use the Group ID, which will then be replaced by the group definition. This makes their behavior more like that of DoxygenTM.

The example markup would look like this:

/*!**************************************************************************** 
* @program  Main program for the Astrology software.                    
*                                                                       
*           Here is some more detailed information.                     
*           For further information see the following                   
*           {@extlink http://www.enache.de Web page}. You may also want 
*           to look at {@extlink http://www.google.com}.                
* @group    types/software                                              
* @group    types/software/astro                                        
* @group    DENACHE                                               
*                                                                       
******************************************************************************/ 

AutoDoc now will expand "DENACHE" to "users/denache"

 

Multi file languages, like C and C++

Some programming languages have their constructs, like classes, spread over multiple files. For example in C, C++ the class definition is defined in the header file *.h and the implementation of the methods are stored in the *.c or *.cpp file.

AutoDoc is by design independent of a programming language. It cannot draw the connaection between the *.cpp and the corresponding *.h file. To get a good result in those languages, consider

Example (header file):

/*!****************************************************************************  
* @library    Containing the header of MyClass. 
*                                               
* @author     Daniel Enache                     
******************************************************************************/ 

#if !defined(MYCLASS_H_INCLUDED_)
#define MYCLASS_H_INCLUDED_

#if _MSC_VER > 1000
#pragma once
#endif // _MSC_VER > 1000

/*!****************************************************************************
* @class "MyClass"           
*     Definition of MyClass. 
* @author  Daniel Enache.    
******************************************************************************/ 
class MyClass
{
    public:
    /*!****************************************************************************  
    * @method "MyClass(int x)"    
    *     Constructor.            
    *                             
    * @param  x    Input integer. 
    ******************************************************************************/ 
    MyClass(int x);
	 
    private:
    /*!  @field    i    Stores the data.      */              
    int i;
};

#endif // !defined(MYCLASS_H_INCLUDED_)

Example (cpp file):

/*!****************************************************************************  
* @library    Containing the implementation of MyClass.
*                                                      
* @author     Daniel Enache                            
******************************************************************************/ 

/*!****************************************************************************  
* @includes "MyClass.h"  Header file for MyClass.
******************************************************************************/ 
#include "MyClass.h"

/*!****************************************************************************  
* @method "MyClass(int x)"    
*     Constructor.            
*                             
* @param  x    Input integer. 
******************************************************************************/ 
MyClass::MyClass(int x)
{
    i = x;
}

Alternatively, you can also include the "MyClass::" prefix to the method tag, but then you must also have a @class tag before in the file, as in the following example:

/*!****************************************************************************  
* @library    Containing the implementation of MyClass.
*                                                      
* @author     Daniel Enache                            
******************************************************************************/ 

/*!****************************************************************************  
* @includes "MyClass.h"  Header file for MyClass.
******************************************************************************/ 
#include "MyClass.h"

/*!****************************************************************************
* @class "MyClass"           
*     Implementation of MyClass. 
* @author  Daniel Enache.    
******************************************************************************/ 

/*!****************************************************************************  
* @method "MyClass::MyClass(int x)"    
*     Constructor.            
*                             
* @param  x    Input integer. 
******************************************************************************/ 
MyClass::MyClass(int x)
{
    i = x;
}

 

Bibliography and Reference Functionality

Version 1.2.5 introduced a bibliography functionality. Bibliography entries can be generated by the Sub-Tags @bib and @bibl. For Example:

/*!**************************************************************************** 
* @function "invswp(x)"
* @brief Calculates the gerneralized sweep inverse of x.
*
* @param x  Argument.
* @return   Resulting inverse.
*
* @bib "Küsters1989" Küsters, U. and Arminger, G. (1989), Programmieren in GAUSS, Gustav Fischer Verlag.              
*                                                                       
******************************************************************************/ 

 

The first argument is a unique identifier for the reference, the last argument the actual entry.

@bib generates a global reference, so the reference does not appear at the location, where is is defined, but rather in a separate global bibliography. For single file output, like "single", "latex" or "pdflatex", it is found at the end of the file. Otherwise, a separate file "Autodoc_Ref.htm" is generated. Links to the bilbliography are added at the appropriate places, like in the navigation trees.

@bibl on the other hand generates a local reference, known only in the current file. The output appears at the locations, where it is defined.

Citations of the bibliography references can be made using the Inline-Tag @cite and the unique identifier, as in this example:

/*!**************************************************************************** 
* @function "regression(y, x)"
* @brief   Calculates linear regression of x on y.
* @details To avoid problems with singular matrices, the generalized inverse
*          described by {@cite "Küsters1989"} is used.
*
* @param y  Vector of the dependent variable.
* @param x  Matrix if independent variables.
* @return   Vector of estimated parameters.
*                                                                       
******************************************************************************/ 

 

AutoDoc generates a marker for the cited reference, if found, and adds a link to the output of the bibliographic reference. Since there are both, global and local references possible, the @cite tag first checks, if there is a global reference with the same ID. If no global reference is found, the local references of the current file are searched.

Global references get an index in square brackets as a marker. For example the entry of the above reference in the bibliography output looks like this, if it is the first reference:

[1] Küsters, U. and Arminger, G. (1989), Programmieren in GAUSS, Gustav Fischer Verlag. {Küsters1989}

The marker of a local reference is the unique ID in curly braces, e.g.:

{Küsters1989} Küsters, U. and Arminger, G. (1989), Programmieren in GAUSS, Gustav Fischer Verlag.

The same markers are used for citations and references and links are added as possible.

 

Examples

File Description Examples

A typical example for a program file description block for a Java program could look as follows:

/*!**************************************************************************** 
* @program  Main program for the Astrology software.                    
*                                                                       
*           For further information see the following                   
*           {@extlink http://www.enache.de Web page}. You may also want 
*           to look at {@extlink http://www.google.com}.                
* @version  1.1                                                         
* @since    Java 1.4                                                     
*                                                                       
* @group    types/software                                              
* @group    types/software/astro                                        
* @group    users/denache                                               
*                                                                       
* @author   Daniel Enache                                               
* @author   Enache Daniel                                               
* @date     29.03.2014                                                  
* @contact  denache@gmx.de                                              
* @contact  denache67@gmail.com                                         
*                                                                       
* @warning  This is a test warning.                                     
*                                                                       
* @howto      1. Install the program.                                   
*             2. Run the program.                                       
*                                                                       
* @input    data/ClientData.csv       Example client data.              
* @input    data/Coordinates.csv      Geo coordinates database.         
* @input    data/CountryCodes.csv     Country codes table.              
* @input    data/TimezoneCountry.csv  Timezone Country matching table.  
*                                                                       
* @output   userdata/ClientData.csv   Users client data.                
* @output   userdata/CurClient.csv    Users current client.             
*                                                                       
* @todo     There is still stuff to do.                                 
*                                                                       
* @history  VERS    DATE        AUTHOR        DESCRIPTION               
* @history   1.0    01.01.2013  "Daniel E."   Initial implementation.   
* @history   1.1    29.03.2014  "Daniel E."   Some corrections.         
******************************************************************************/ 

Here is another example for a SAS program:

/*!****************************************************************************  
* @program   Main program for the creation of the datamart.            
*                                                                      
*            This is a second paragraph.                               
* @version   3.0                                                       
* @since     SAS 9.03                                                  
*                                                                      
* @group     types / datamart                                          
* @group     users / denache                                           
*                                                                      
* @author    Daniel Enache                                             
* @date      12.07.2013                                                
* @contact   denache@gmx.de                                            
*                                                                      
* @warning   This is a test warning.                                   
*                                                                      
* @howto     1. Set the macro variable paramter BAUMON to the last     
*               complete month.                                        
*            2. Run the program.                                       
*                                                                      
* @param     BAUMON      Month for the BAU run in YYYYMM format. Will  
*                        be set automatically by the calling routine.  
* @input     TAB1yyyy    Input table 1.                                
* @input     TAB2yyyy    Input table 2.                                
* @input     TAB3yyyy    Input table 3.                                
*                                                                      
* @output    OUT_TAB1yyyy  Output table 1.                             
* @output    OUT_TAB2yyyy  Output table 2.                             
*                                                                      
* @calls  {buildDM_BAU(STARTMON, ENDMON)}                              
*                                                                      
* @todo      There is still stuff to do.                               
*                                                                      
* @licence   {@link http://www.gnu.org/licenses/ GPL 3.0}              
*                                                                      
* @history    VERS    DATE        AUTHOR      DESCRIPTION              
* @history    3.0     01.01.2013  DE          Initial implementation. 
* @history    3.0     12.07.2013  DE          Corrections calculation.
******************************************************************************/  

and here one for a SAS library:

/*!****************************************************************************
* @library    Contains some utility macros.                         
*                                                                   
*             For addtional information see                         
*             {@extlink http://www.google.de/ Google Suchseite}.    
* @version    3.0                                                   
* @since      SAS 9.03                                                
* @author     Daniel Enache                                         
* @date       01.01.2013                                            
* @contact    denache@gmx.de                                        
*                                                                   
* @history  VERS     DATE        AUTHOR      DESCRIPTION            
* @history   3.0     01.01.2013  DE          Initial implementation.
******************************************************************************/  

Here now an example for an AutoIt program, which uses a different comment character (a semi-colon ";") and therefore different block markers (see the section about the respective command line parameters.):

;*!***************************************************************************
;* @program    Test program for AutoIt.      
;*                                           
;*             This is a second paragraph.   
;* @version    3.0                           
;* @since      AutoIt 3.0                      
;*                                           
;* @group      types/utilities               
;* @group      users/denache                 
;*                                           
;* @author     Daniel Enache                 
;* @date       12.07.2013                    
;* @contact    denache@gmx.de                
;*                                           
;***************************************************************************!*;  

 

Structure Description Examples

Long programs can be structured by marking up sections. Also include files can be marked up and will be shown in the structure view. Here is an example for a SAS program (actual program code is omitted and replaced by "..."):

/*!******************************************************************************* 
* @program  Main Program of the Reporting.
*********************************************************************************/  

...

/*!
* @includes	"C:\some\dir\Signon.sas"	         Standard login to DWH.  
*/

...

/*!**************************************************************************** 
* @progsection Parameters.
******************************************************************************/  

...

/*!**************************************************************************** 
* @progsection Initialization and definition of libnames. 
******************************************************************************/  

...

rsubmit;
/*! @includes  "/some/netpath/DWH_ZipUnzip_Lib.sas"   Import Zip-/Unzip Library.  */
...
endrsubmit;

/*!
* @includes  ".\include\Formats.sas"        Import formats.
* @includes  ".\include\OutputUtils.sas"    Import output untility macros.
*/
...

/*!**************************************************************************** 
* @progsection Utility Macros. 
******************************************************************************/  

...

/*!
* @includes  ".\include\CheckTriggers.sas"  Checks, if the input data is available. If not, the program ist terminated. 
*/
...


/*!**************************************************************************** 
* @progsection Calculation of Data. 
******************************************************************************/  

/*!
* @includes	".\include\Calculation_1.sas"     Type 1 recalculation. 
* @includes	".\include\Calculation_2.sas"     Type 2 recalculation.
*/
...

/*!**************************************************************************** 
* @progsection Data creation for Type 1 reports. 
******************************************************************************/  
...

/*!**************************************************************************** 
* @progsection Data creation for type 2.
******************************************************************************/  

...


/*!**************************************************************************** 
* @progsection All Reports of type 1 without performance. 
******************************************************************************/  

/*!
* @includes	".\include\Report_1_1.sas"     Generates report type 1 on type 1 data.
* @includes	".\include\Report_1_2.sas"     Generates report type 2 on type 1 data.
* @includes	".\include\Report_1_3.sas"     Generates report type 3 on type 1 data.
*/

...

/*!**************************************************************************** 
* @progsection Data creation for reports with performance. 
******************************************************************************/  

...

/*!**************************************************************************** 
* @progsection All reports with performance.
******************************************************************************/  
 
/*!
* @includes	".\include\Report_2_1.sas"       Generates report 1 for type 2 data.
* @includes	".\include\Report_2_1.sas"       Generates report 2 for type 2 data.
*/

...

/*!**************************************************************************** 
* @progsection Finish of program. 
******************************************************************************/  
...

/*!
* @includes ".\include\CopyToProduction.sas"    Copy Reports to Production Directories.
*/

...

This will produce the following structure output:

 

Java or C++ classes also belong into this category. Here is an example for a Java class description:

/*!****************************************************************************
* @class DateCalc  Class which capsules the GregorianCalendar class which
*        is easier to handle and allows various calculations.            
*                                                                        
* @implements Comparable<DateCalc>                                 
* @author Daniel Enache                                                  
* @version 1.0                                                           
******************************************************************************/ 

 

Functional Descriptions Examples

This is a typical markup block for a Java method:

/*!****************************************************************************
* @method "public int compareTo(DateCalc o)"                         
*    Compares the current DateCalc object to another DateCalc object.
*    Time zone differences are automatically considered.             
*                                                                    
* @param s     DateCalc object.                                      
*                                                                    
* @return 0 if equal, -1 if current object is less and 1 if current  
*         object ist greater.                                        
******************************************************************************/ 

And here an example for a SAS macro definition:

/*!****************************************************************************
* @macro  "getRows(table)"                   
*         Gets the number of rows of a table.
*                                            
* @param table    SAS table name.            
*                                            
* @return         Resulting row number.      
******************************************************************************/ 

This next example is a function / procedure declaration in the AutoIt Language:

;*!***************************************************************************;  
;* @function  "Test2($sMsg)"                                    
;*            Strips leading and trailing blanks from a string. 
;* @date    12.03.2104                                          
;* @author  Daniel Enache                                       
;*                                                              
;* @todo    This function must be renamed.                      
;*                                                              
;* @param   $sMsg    String to be stripped.                     
;* @return  Stripped string.                                    
;***************************************************************************!*;

 

Index of all Tags

This is the list of all supported tags in alphabetical order for each type:

Tag TypeTagDescriptionNo. Param.Syntax
File@excludeMarks the file to be excluded from documentation.1@exclude Description
File@fileDefines the file as a general file.1@file Description
File@libraryDefines the file as a library.1@library Description
File@programDefines the file as a program.1@program Description
File@subprogramDefines the file as a sub program which is part of a bigger program.1@subprogram Description
Structure@classMarks the beginning of a class.2@class Classname Description
Structure@includesDescribes included files.2@includes Filename Description
Structure@interfaceMarks the beginning of an interface.2@interface Interfacename Description
Structure@progsectionMarks the beginning of a logical section.1@progsection Description
Structure@stepDescribes a step (e.g. a SAS step or proc).1@step Stepname Description
Functional@fieldDescribes a class field.2@field Fieldname Description
Functional@formatDescribes a format definition.2@format Formatname Description
Functional@functionDescribes a function.2@function Functionname Description
Functional@macroDescribes a macro.2@macro Macroname Description
Functional@methodDescribes a class method.2@method Methodname Description
Functional@procedureDescribes a procedure.2@procedure Functionname Description
Functional@saslibnameDescribes a SAS local libname.3@saslibname Name Definition Description
Functional@sasrlibnameDescribes a SAS remote libname.3@sasrlibname Name Definition Description
Functional@variableDescribes a variable.2@variable Variablename Description
Sub@attentionAdds attention information.1@attention Description
Sub@authorAdds author information.1@author Authorname
Sub@beginsrcquoteMarks that subsequent code up to is quoted endsrcquote in the output.0@beginsrcquote
Sub@bibAdds a global bibliography reference.2@bib UniqueID Bibliography Entry
Sub@biblAdds a local bibliography reference.2@bibl UniqueID Bibliography Entry
Sub@bugAdds bug information.1@bug Description
Sub@briefAdds brief description (for DoxygenTM compatibility only).1@brief Description
Sub@callsAdds function, method, or macro which is called. Experimental.1@calls RoutineName
Sub@changesAdds information about changes.1@changes Changes information
Sub@chgreasonAdds information about change reasons.1@chgreason Change reason information
Sub@classificationAdds classification information.1@classification Classification information
Sub@clientAdds client information.1@client Clientname
Sub@commentSuppresses output of the following parameter.1@comment Suppressed
Sub@companyAdds company information.1@company Company information
Sub@contactAdds contact information.1@contact Contactinfo
Sub@copyrightAdds copyright information.1@copyright Description
Sub@dateAdds date information.1@date Date
Sub@departmentAdds deparment information.1@department Deparment information
Sub@deprecatedMarks the parent tag as deprecated.1@deprecated Description
Sub@detailsAdds detailed description (for DoxygenTM compatibility only).1@details Description
Sub@directoryAdds directory information.2@directory Directory-Name Directory
Sub@docuAdds documentation information.1@docu Description
Sub@durationAdds information about the duration of the program run.1@duration Description
Sub@endsrcquoteMarks that code since beginsrcquote is quoted in the output.0@endsrcquote
Sub@exampleAdds an example.1@example Description
Sub@extendsAdds information about the parent class.1@extends Description
Sub@freqAdds information about the excecution frequency of the program.1@freq Description
Sub@groupAdds group information.1@group Groupname
Sub@hiddengroupAdds group information.1@hiddengroup Groupname
Sub@historyAdds history log information.4@history Version Date Author Description
Sub@howtoAdds usage information.1@howto Description
Sub@implementsAdds information about the implemented interface.1@implements Description
Sub@includeadIncludes AutoDoc markup from a file.1@includead Filename
Sub@inputDescribes input data.2@input InputName Description
Sub@licenceDescribes the underlying software licence.1@licence Description
Sub@moduleAdds module information.1@module Namespace name
Sub@namespaceAdds namespace information.1@namespace Namespace name
Sub@noteAdds a note.1@note Description
Sub@outfileAdds output file information1@outfile Description
Sub@outpathAdds output path information1@outpath Description
Sub@outputDescribes output data.2@output OutputName Description
Sub@packageAdds package information.1@package Package name
Sub@paramAdds information about a parameter.2@param Name Description
Sub@permissionAdds permission information.1@permission Permission information
Sub@postcondAdds post-condition information.1@postcond Description
Sub@precondAdds pre-condition information.1@precond Description
Sub@returnAdds information about the return value.1@return Description
Sub@requestorAdds requestor information.1@requestor Requestorname
Sub@reviewerAdds reviewer information.1@reviewer Name
Sub@seeAdds a cross reference description.1@see Reference Description
Sub@sectionAdds information of a user defined section.1@section Section-Heading Description
Sub@sinceAdds minimum compiler / interpeter version.1@since Version
Sub@statusAdds status information.1@status Status-Information
Sub@testdocAdds test documentation information.1@testdoc Test documentation
Sub@testerAdds tester information.1@tester Name
Sub@throwsDeclares a thrown exception.1@throws Exceptionname
Sub@todoAdds TODO information.1@todo Description
Sub@userAdds user information.1@user Authorname
Sub@versionAdds version information.1@version Version
Sub@warningAdds warning information.1@warning Description
Inline@bSets the text in bold font.1{@b Text}
Inline@biSets the text in bold italic font.1{@bi Text}
Inline@bisSets the text in bold italic strike-through font.1{@bis Text}
Inline@biuSets the text in bold italic underlined font.1{@biu Text}
Inline@bsSets the text in bold strike-through font.1{@bs Text}
Inline@buSets the text in bold underlined font.1{@bu Text}
Inline@citeAdds a reference to a bib item.1{@cite UniqueID}
Inline@codeAdds source code.1{@code Codefragment}
Inline@emSets the text in emphasized font.1{@em Text}
Inline@esSets the text in emphasized strike-through font.1{@es Text}
Inline@euSets the text in emphasized underlined font.1{@eu Text}
Inline@extlinkAdds an external link to another document.2{@extlink URL Label}
Inline@iSets the text in italic font.1{@i Text}
Inline@imgAdds an image.2{@img Image-File Vertical-Orientation}
Inline@newlineInserts a new line.0{@newline}
Inline@linkAdds an internal link to another document.2{@link URL Label}
Inline@qInserts a single quote character '.0{@q}
Inline@qqInserts a double quote character ".0{@qq}
Inline@sSets the text in strike-through font.1{@s Text}
Inline@ttSets the text in typewriter font.1{@tt Text}
Inline@ttbSets the text in typewriter bold font.1{@ttb Text}
Inline@ttbiSets the text in typewriter bold italic font.1{@ttbi Text}
Inline@ttbisSets the text in typewriter bold italic strike-through font.1{@ttbis Text}
Inline@ttbiuSets the text in typewriter bold italic underlined font.1{@ttbiu Text}
Inline@ttbsSets the text in typewriter bold strike-through font.1{@ttbs Text}
Inline@ttbuSets the text in typewriter bold underlined font.1{@ttbu Text}
Inline@ttiSets the text in typewriter italic font.1{@tti Text}
Inline@ttisSets the text in typewriter italic strike-through font.1{@ttis Text}
Inline@ttiuSets the text in typewriter italic underlined font.1{@ttiu Text}
Inline@ttsSets the text in typewriter strike-through font.1{@tts Text}
Inline@ttuSets the text in typewriter underlined font.1{@ttu Text}
Inline@uSets the text in underlined font.1{@u Text}

 

For compatibility with DoxygenTM there are also defined additional tags, which are basically aliases of the tags described above. This way, it is easier to port your doxygen markups to AutoDoc. This also enables compatibility with oler AutoDoc versions, when a tag name has been changed.

Tag TypeTagDescriptionNo. Param.Syntax
File@headerfileAlias for @library.1@headerfile Description
Functional@fnAlias for @function.2@fn Functionname Description
Functional@propertyAlias for @field.2@property Fieldname Description
Functional@varAlias for @variable.2@var Variablename Description
Sub@addtogroupAlias for @group.1@addtogroup Groupname
Sub@authorsAlias for @author.1@authors Authorname
Sub@checkerAlias for @reviewer.1@checker Authorname
Sub@defgroupAlias for @group.1@defgroup Groupname
Sub@ingroupAlias for @group.1@ingroup Groupname
Sub@postAlias for @postcond.1@post Description
Sub@preAlias for @precond.1@pre Description
Sub@returnsAlias for @return.1@returns Description
Sub@retvalAlias for @return.1@retval Description
Sub@saAlias for @see.1@sa Reference Description
Sub@shortAlias for @brief.1@short Description
Sub@throwAlias for @throws.1@throw Exceptionname
Sub@weakgroupAlias for @group.1@weakgroup Groupname
Inline@aAlias for @i.1{@a Text}
Inline@cAlias for @tt.1{@c Text}
Inline@eAlias for @em.1{@e Text}
Inline@pAlias for @tt.1{@p Text}
Inline@refAlias for @link.2{@ref URL Label}
Inline@verbatimAlias for @tt.1{@verbatim Text}