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.
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.
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. *********************************************/
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:
Tag | Description | No. Param. | Syntax |
---|---|---|---|
@exclude | Marks the file to be excluded from documentation. | 1 | @exclude Description |
@file | Defines the file as a general file. | 1 | @file Description |
@library | Defines the file as a library. | 1 | @library Description |
@program | Defines the file as a program. | 1 | @program Description |
@subprogram | Defines 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:
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:
Tag | Description | No. Param. | Syntax |
---|---|---|---|
@class | Marks the beginning of a class. | 2 | @class Classname Description |
@includes | Describes included files. | 2 | @includes Filename Description |
@interface | Marks the beginning of an interface. | 2 | @interface Interfacename Description |
@progsection | Marks the beginning of a logical section. | 1 | @progsection Description |
@step | Describes 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 are used to markup functions, methods, macros, etc. The follwoing tags are supported by AutoDoc and all have 2 parameters:
Tag | Description | No. Param. | Syntax |
---|---|---|---|
@field | Describes a class field. | 2 | @field Fieldname Description |
@format | Describes a format definition. | 2 | @format Formatname Description |
@function | Describes a function. | 2 | @function Functionname Description |
@macro | Describes a macro. | 2 | @macro Macroname Description |
@method | Describes a class method. | 2 | @method Methodname Description |
@procedure | Describes a procedure. | 2 | @procedure Functionname Description |
@saslibname | Describes a SAS local libname. | 3 | @saslibname Name Definition Description |
@sasrlibname | Describes a SAS remote libname. | 3 | @sasrlibname Name Definition Description |
@variable | Describes 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 can be used to provide additional information for all the tags presented above. The following sub tags are available in AutoDoc:
Tag | Description | No. Param. | Syntax |
---|---|---|---|
@attention | Adds attention information. | 1 | @attention Description |
@author | Adds author information. | 1 | @author Authorname |
@beginsrcquote | Marks that subsequent code up to is quoted endsrcquote in the output. | 0 | @beginsrcquote |
@bib | Adds a global bibliography reference. | 2 | @bib UniqueID Bibliography Entry |
@bibl | Adds a local bibliography reference. | 2 | @bibl UniqueID Bibliography Entry |
@brief | Adds brief description (for DoxygenTM compatibility only). | 1 | @brief Description |
@bug | Adds bug information. | 1 | @bug Description |
@calls | Adds function, method, or macro which is called. Experimental. | 1 | @calls RoutineName |
@changes | Adds information about changes. | 1 | @changes Changes information |
@chgreason | Adds information about change reasons. | 1 | @chgreason Change reason information |
@classification | Adds classification information. | 1 | @classification Classification information |
@client | Adds client information. | 1 | @client Clientname |
@comment | Suppresses output of the following parameter. | 1 | @comment Suppressed |
@company | Adds company information. | 1 | @company Company information |
@contact | Adds contact information. | 1 | @contact Contactinfo |
@copyright | Adds copyright information. | 1 | @copyright Description |
@date | Adds date information. | 1 | @date Date |
@department | Adds deparment information. | 1 | @department Deparment information |
@deprecated | Marks the parent tag as deprecated. | 1 | @deprecated Description |
@details | Adds detailed description (for DoxygenTM compatibility only). | 1 | @details Description |
@directory | Adds directory information. | 2 | @directory Directory-Name Directory |
@docu | Adds documentation information. | 1 | @docu Description |
@duration | Adds information about the duration of the program run. | 1 | @duration Description |
@endsrcquote | Marks that code since beginsrcquote is quoted in the output. | 0 | @endsrcquote |
@example | Adds an example. | 1 | @example Description |
@extends | Adds information about the parent class. | 1 | @extends Description |
@freq | Adds information about the excecution frequency of the program. | 1 | @freq Description |
@group | Adds group information. | 1 | @group Groupname |
@hiddengroup | Adds group information. | 1 | @hiddengroup Groupname |
@history | Adds history log information. | 4 | @history Version Date Author Description |
@howto | Adds usage information. | 1 | @howto Description |
@implements | Adds information about the implemented interface. | 1 | @implements Description |
@includead | Includes AutoDoc markup from a file. | 1 | @includead Filename |
@input | Describes input data. | 2 | @input InputName Description |
@licence | Describes the underlying software licence. | 1 | @licence Description |
@module | Adds module information. | 1 | @module Namespace name |
@namespace | Adds namespace information. | 1 | @namespace Namespace name |
@note | Adds a note. | 1 | @note Description |
@outfile | Adds output file information | 1 | @outfile Description |
@outpath | Adds output path information | 1 | @outpath Description |
@output | Describes output data. | 2 | @output OutputName Description |
@package | Adds package information. | 1 | @package Package name |
@param | Adds information about a parameter. | 2 | @param Name Description |
@permission | Adds permission information. | 1 | @permission Permission information |
@postcond | Adds post-condition information. | 1 | @postcond Description |
@precond | Adds pre-condition information. | 1 | @precond Description |
@return | Adds information about the return value. | 1 | @return Description |
@requestor | Adds requestor information. | 1 | @requestor Requestorname |
@reviewer | Adds reviewer information. | 1 | @reviewer Name |
@section | Adds information of a user defined section. | 1 | @section Section-Heading Description |
@see | Adds a cross reference description. | 1 | @see Reference Description |
@since | Adds minimum compiler / interpeter version. | 1 | @since Version |
@status | Adds status information. | 1 | @status Status-Information |
@testdoc | Adds test documentation information. | 1 | @testdoc Test documentation |
@tester | Adds tester information. | 1 | @tester Name |
@throws | Declares a thrown exception. | 1 | @throws Exceptionname |
@todo | Adds TODO information. | 1 | @todo Description |
@user | Adds user information. | 1 | @user Authorname |
@version | Adds version information. | 1 | @version Version |
@warning | Adds 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".
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.
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 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:
Tag | Description | No. Param. | Syntax |
---|---|---|---|
@b | Sets the text in bold font. | 1 | {@b Text} |
@bi | Sets the text in bold italic font. | 1 | {@bi Text} |
@bis | Sets the text in | 1 | {@bis Text} |
@biu | Sets the text in bold italic underlined font. | 1 | {@biu Text} |
@bs | Sets the text in | 1 | {@bs Text} |
@bu | Sets the text in bold underlined font. | 1 | {@bu Text} |
@cite | Adds a reference to a bib item. | 1 | {@cite UniqueID} |
@code | Adds source code. | 1 | {@code Codefragment} |
@em | Sets the text in emphasized font. | 1 | {@em Text} |
@es | Sets the text in | 1 | {@es Text} |
@eu | Sets the text in emphasized underlined font. | 1 | {@eu Text} |
@extlink | Adds an external link to another document. | 2 | {@extlink URL Label} |
@i | Sets the text in italic font. | 1 | {@i Text} |
@img | Adds an image. | 2 | {@img Image-File Vertical-Orientation} |
@newline | Inserts a new line. | 0 | {@newline} |
@link | Adds an internal link to another document. | 2 | {@link URL Label} |
@q | Inserts a single quote character '. | 0 | {@q} |
Inserts a double quote character ". | 0 | {@qq} | |
@s | Sets the text in | 1 | {@s Text} |
@tt | Sets the text in typewriter font. | 1 | {@tt Text} |
@ttb | Sets the text in typewriter bold font. | 1 | {@ttb Text} |
@ttbi | Sets the text in typewriter bold italic font. | 1 | {@ttbi Text} |
@ttbis | Sets the text in | 1 | {@ttbis Text} |
@ttbiu | Sets the text in typewriter bold italic underlined font. | 1 | {@ttbiu Text} |
@ttbs | Sets the text in | 1 | {@ttbs Text} |
@ttbu | Sets the text in typewriter bold underlined font. | 1 | {@ttbu Text} |
@tti | Sets the text in typewriter italic font. | 1 | {@tti Text} |
@ttis | Sets the text in | 1 | {@ttis Text} |
@ttiu | Sets the text in typewriter italic underlined font. | 1 | {@ttiu Text} |
@tts | Sets the text in | 1 | {@tts Text} |
@ttu | Sets the text in typewriter underlined font. | 1 | {@ttu Text} |
@u | Sets 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.
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"
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; }
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.
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 ;* ;***************************************************************************!*;
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 ******************************************************************************/
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. ;***************************************************************************!*;
This is the list of all supported tags in alphabetical order for each type:
Tag Type | Tag | Description | No. Param. | Syntax |
---|---|---|---|---|
File | @exclude | Marks the file to be excluded from documentation. | 1 | @exclude Description |
File | @file | Defines the file as a general file. | 1 | @file Description |
File | @library | Defines the file as a library. | 1 | @library Description |
File | @program | Defines the file as a program. | 1 | @program Description |
File | @subprogram | Defines the file as a sub program which is part of a bigger program. | 1 | @subprogram Description |
Structure | @class | Marks the beginning of a class. | 2 | @class Classname Description |
Structure | @includes | Describes included files. | 2 | @includes Filename Description |
Structure | @interface | Marks the beginning of an interface. | 2 | @interface Interfacename Description |
Structure | @progsection | Marks the beginning of a logical section. | 1 | @progsection Description |
Structure | @step | Describes a step (e.g. a SAS step or proc). | 1 | @step Stepname Description |
Functional | @field | Describes a class field. | 2 | @field Fieldname Description |
Functional | @format | Describes a format definition. | 2 | @format Formatname Description |
Functional | @function | Describes a function. | 2 | @function Functionname Description |
Functional | @macro | Describes a macro. | 2 | @macro Macroname Description |
Functional | @method | Describes a class method. | 2 | @method Methodname Description |
Functional | @procedure | Describes a procedure. | 2 | @procedure Functionname Description |
Functional | @saslibname | Describes a SAS local libname. | 3 | @saslibname Name Definition Description |
Functional | @sasrlibname | Describes a SAS remote libname. | 3 | @sasrlibname Name Definition Description |
Functional | @variable | Describes a variable. | 2 | @variable Variablename Description |
Sub | @attention | Adds attention information. | 1 | @attention Description |
Sub | @author | Adds author information. | 1 | @author Authorname |
Sub | @beginsrcquote | Marks that subsequent code up to is quoted endsrcquote in the output. | 0 | @beginsrcquote |
Sub | @bib | Adds a global bibliography reference. | 2 | @bib UniqueID Bibliography Entry |
Sub | @bibl | Adds a local bibliography reference. | 2 | @bibl UniqueID Bibliography Entry |
Sub | @bug | Adds bug information. | 1 | @bug Description |
Sub | @brief | Adds brief description (for DoxygenTM compatibility only). | 1 | @brief Description |
Sub | @calls | Adds function, method, or macro which is called. Experimental. | 1 | @calls RoutineName |
Sub | @changes | Adds information about changes. | 1 | @changes Changes information |
Sub | @chgreason | Adds information about change reasons. | 1 | @chgreason Change reason information |
Sub | @classification | Adds classification information. | 1 | @classification Classification information |
Sub | @client | Adds client information. | 1 | @client Clientname |
Sub | @comment | Suppresses output of the following parameter. | 1 | @comment Suppressed |
Sub | @company | Adds company information. | 1 | @company Company information |
Sub | @contact | Adds contact information. | 1 | @contact Contactinfo |
Sub | @copyright | Adds copyright information. | 1 | @copyright Description |
Sub | @date | Adds date information. | 1 | @date Date |
Sub | @department | Adds deparment information. | 1 | @department Deparment information |
Sub | @deprecated | Marks the parent tag as deprecated. | 1 | @deprecated Description |
Sub | @details | Adds detailed description (for DoxygenTM compatibility only). | 1 | @details Description |
Sub | @directory | Adds directory information. | 2 | @directory Directory-Name Directory |
Sub | @docu | Adds documentation information. | 1 | @docu Description |
Sub | @duration | Adds information about the duration of the program run. | 1 | @duration Description |
Sub | @endsrcquote | Marks that code since beginsrcquote is quoted in the output. | 0 | @endsrcquote |
Sub | @example | Adds an example. | 1 | @example Description |
Sub | @extends | Adds information about the parent class. | 1 | @extends Description |
Sub | @freq | Adds information about the excecution frequency of the program. | 1 | @freq Description |
Sub | @group | Adds group information. | 1 | @group Groupname |
Sub | @hiddengroup | Adds group information. | 1 | @hiddengroup Groupname |
Sub | @history | Adds history log information. | 4 | @history Version Date Author Description |
Sub | @howto | Adds usage information. | 1 | @howto Description |
Sub | @implements | Adds information about the implemented interface. | 1 | @implements Description |
Sub | @includead | Includes AutoDoc markup from a file. | 1 | @includead Filename |
Sub | @input | Describes input data. | 2 | @input InputName Description |
Sub | @licence | Describes the underlying software licence. | 1 | @licence Description |
Sub | @module | Adds module information. | 1 | @module Namespace name |
Sub | @namespace | Adds namespace information. | 1 | @namespace Namespace name |
Sub | @note | Adds a note. | 1 | @note Description |
Sub | @outfile | Adds output file information | 1 | @outfile Description |
Sub | @outpath | Adds output path information | 1 | @outpath Description |
Sub | @output | Describes output data. | 2 | @output OutputName Description |
Sub | @package | Adds package information. | 1 | @package Package name |
Sub | @param | Adds information about a parameter. | 2 | @param Name Description |
Sub | @permission | Adds permission information. | 1 | @permission Permission information |
Sub | @postcond | Adds post-condition information. | 1 | @postcond Description |
Sub | @precond | Adds pre-condition information. | 1 | @precond Description |
Sub | @return | Adds information about the return value. | 1 | @return Description |
Sub | @requestor | Adds requestor information. | 1 | @requestor Requestorname |
Sub | @reviewer | Adds reviewer information. | 1 | @reviewer Name |
Sub | @see | Adds a cross reference description. | 1 | @see Reference Description |
Sub | @section | Adds information of a user defined section. | 1 | @section Section-Heading Description |
Sub | @since | Adds minimum compiler / interpeter version. | 1 | @since Version |
Sub | @status | Adds status information. | 1 | @status Status-Information |
Sub | @testdoc | Adds test documentation information. | 1 | @testdoc Test documentation |
Sub | @tester | Adds tester information. | 1 | @tester Name |
Sub | @throws | Declares a thrown exception. | 1 | @throws Exceptionname |
Sub | @todo | Adds TODO information. | 1 | @todo Description |
Sub | @user | Adds user information. | 1 | @user Authorname |
Sub | @version | Adds version information. | 1 | @version Version |
Sub | @warning | Adds warning information. | 1 | @warning Description |
Inline | @b | Sets the text in bold font. | 1 | {@b Text} |
Inline | @bi | Sets the text in bold italic font. | 1 | {@bi Text} |
Inline | @bis | Sets the text in | 1 | {@bis Text} |
Inline | @biu | Sets the text in bold italic underlined font. | 1 | {@biu Text} |
Inline | @bs | Sets the text in | 1 | {@bs Text} |
Inline | @bu | Sets the text in bold underlined font. | 1 | {@bu Text} |
Inline | @cite | Adds a reference to a bib item. | 1 | {@cite UniqueID} |
Inline | @code | Adds source code. | 1 | {@code Codefragment} |
Inline | @em | Sets the text in emphasized font. | 1 | {@em Text} |
Inline | @es | Sets the text in | 1 | {@es Text} |
Inline | @eu | Sets the text in emphasized underlined font. | 1 | {@eu Text} |
Inline | @extlink | Adds an external link to another document. | 2 | {@extlink URL Label} |
Inline | @i | Sets the text in italic font. | 1 | {@i Text} |
Inline | @img | Adds an image. | 2 | {@img Image-File Vertical-Orientation} |
Inline | @newline | Inserts a new line. | 0 | {@newline} |
Inline | @link | Adds an internal link to another document. | 2 | {@link URL Label} |
Inline | @q | Inserts a single quote character '. | 0 | {@q} |
Inline | Inserts a double quote character ". | 0 | {@qq} | |
Inline | @s | Sets the text in | 1 | {@s Text} |
Inline | @tt | Sets the text in typewriter font. | 1 | {@tt Text} |
Inline | @ttb | Sets the text in typewriter bold font. | 1 | {@ttb Text} |
Inline | @ttbi | Sets the text in typewriter bold italic font. | 1 | {@ttbi Text} |
Inline | @ttbis | Sets the text in | 1 | {@ttbis Text} |
Inline | @ttbiu | Sets the text in typewriter bold italic underlined font. | 1 | {@ttbiu Text} |
Inline | @ttbs | Sets the text in | 1 | {@ttbs Text} |
Inline | @ttbu | Sets the text in typewriter bold underlined font. | 1 | {@ttbu Text} |
Inline | @tti | Sets the text in typewriter italic font. | 1 | {@tti Text} |
Inline | @ttis | Sets the text in | 1 | {@ttis Text} |
Inline | @ttiu | Sets the text in typewriter italic underlined font. | 1 | {@ttiu Text} |
Inline | @tts | Sets the text in | 1 | {@tts Text} |
Inline | @ttu | Sets the text in typewriter underlined font. | 1 | {@ttu Text} |
Inline | @u | Sets 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 Type | Tag | Description | No. Param. | Syntax |
---|---|---|---|---|
File | @headerfile | Alias for @library. | 1 | @headerfile Description |
Functional | @fn | Alias for @function. | 2 | @fn Functionname Description |
Functional | @property | Alias for @field. | 2 | @property Fieldname Description |
Functional | @var | Alias for @variable. | 2 | @var Variablename Description |
Sub | @addtogroup | Alias for @group. | 1 | @addtogroup Groupname |
Sub | @authors | Alias for @author. | 1 | @authors Authorname |
Sub | @checker | Alias for @reviewer. | 1 | @checker Authorname |
Sub | @defgroup | Alias for @group. | 1 | @defgroup Groupname |
Sub | @ingroup | Alias for @group. | 1 | @ingroup Groupname |
Sub | @post | Alias for @postcond. | 1 | @post Description |
Sub | @pre | Alias for @precond. | 1 | @pre Description |
Sub | @returns | Alias for @return. | 1 | @returns Description |
Sub | @retval | Alias for @return. | 1 | @retval Description |
Sub | @sa | Alias for @see. | 1 | @sa Reference Description |
Sub | @short | Alias for @brief. | 1 | @short Description |
Sub | @throw | Alias for @throws. | 1 | @throw Exceptionname |
Sub | @weakgroup | Alias for @group. | 1 | @weakgroup Groupname |
Inline | @a | Alias for @i. | 1 | {@a Text} |
Inline | @c | Alias for @tt. | 1 | {@c Text} |
Inline | @e | Alias for @em. | 1 | {@e Text} |
Inline | @p | Alias for @tt. | 1 | {@p Text} |
Inline | @ref | Alias for @link. | 2 | {@ref URL Label} |
Inline | @verbatim | Alias for @tt. | 1 | {@verbatim Text} |