General information

When commenting the source code, Adelia developers can indicate that a comment must be integrated into the technical documentation using a dedicated syntax called an "annotation".

Depending on the type of program, annotations must be inserted in a specific place in the source code:

For Visual programs: whether it is a program, procedure or management rule, annotations must be placed in the declaration blocks (DECL PGM/DECLARATION) before using the PARAM instruction.
For Adelia programs: to ensure readability, annotations must be placed at the beginning of the source and in all cases before the RECEIVE instruction.
For classes: annotations are not supported in the class sources.
However, for classes referenced in Visual programs, AdeliaDoc uses the class option and *SER_DESC attribute to insert a customized description when generating the class documentation.

Syntax

All AdeliaDoc annotations observe the same syntax rules, as described below:

An annotation is comprised of a keyword and one or more parameters.
A keyword always starts with the "*@" digraph.
The ":" character is used as a separator between the keyword and the parameters; "blank" characters may be inserted before or after the separator character.
The "," character is used as a parameter separator; it is not advisable to insert " blank " characters before or after the separator character.
A keyword is not case sensitive but its parameters are.
An annotation must be at the start of a line (but it can be preceded by " blank " or "tabulation" characters).
Annotation parameters corresponding to text descriptions can be entered over several lines. In this case:

- the "*@" digraph must mark the start of the new line,
- if you need to maintain the multiline formatting in the document, the "*@|" trigraph must mark the start of the new line.
Examples:
- Simple annotation with one parameter:
  *@deprecated : 3.2.5
- Annotation with a multiline parameter - in this example, the description will appear in the form of two lines in the documentation:
  *@description : Selection of an unrecorded item code.
  *@|The P_DISP_ALL parameter must be initialized to the 0 value
  *@to filter on unrecorded and active items.
  Result obtained in the documentation:
```
Selection of an unrecorded item code
The P_DISP_ALL parameter must be initialized to the 0 value to filter on unrecorded and active items.
```

↑ Top of page

Description table of supported annotations

Each of the annotations referenced below can be used interchangeably in a program or procedure declaration block.

From now on in this document, the term "section" will be used to refer to these blocks (as a reminder, in the case of Adelia type programs, annotations must be entered at the start of the program, before the RECEIVE order).

Annotation	Role
`*@adeliadoc`	Used to label (i.e. tag) a section in order to apply filter rules when producing documentation.
`*@description`	Section description
`*@param`	Section parameter description
`*@field`	Description of a field associated with a "`List`" type parameter
`*@version`	Indicates a section's version
`*@author`	Name of section developer
`*@since`	Indicates which version the section has been added since
`*@date`	Date of last section modification
`*@deprecated`	Indicates that the section is deprecated
`*@index`	Used to add an index entry associated with the section to the documentation's global index

It is understood that all annotations are optional. Bearing in mind that for a specific section, when only some or none of the required annotations have been entered, where possible, and if the AdeliaDoc configuration allows, default values from the source analysis and Adelia program description information are used instead to produce the documentation.

↑ Top of page

Detailed description of annotations

In the rest of the document:

the term "markup" indicates that it is possible to use certain elements of the reStructuredText syntax or certain Sphinx roles to format text content and primarily to add links to other sections of the documentation.
You are, however, strongly advised not to use formatting elements intensively or inappropriately as the correct display in the produced documentation cannot be completely guaranteed.
When adding hypertext links, AdeliaDoc requires specific coding to identify the sections, which needs to be observed if you want to use the ad hoc ":ref:" role:
- Program section identification: the identifier is the name of the program itself.
  *@description: this program corresponds to a variation of the margin calculation compared to the version proposed in the program :ref:'COMPUTE_PROFIT'.
- Procedure section identification: the identifier is the concatenation of the program name and the procedure name in PROGRAM.PROC form.
  *@description: this program corresponds to a variation of the margin calculation compared to the version proposed in the procedure :ref:'COMMONSPROCS.PROC_PROFIT'.
- Class section identification: the class identifier is expressed as follows: class_CLASSNAME:
  *@description: this program uses the class :ref:'class_ORDER' to create an order.
The concept of "default value" corresponds to the provenance of the substitution data when the corresponding annotation has not been entered by the developer (taking into account substitution rules from AdeliaDoc configuration parameters)

*@adeliadoc

Role	Used to label (i.e. tag) a section, mainly to identify target audience categories. Directly linked to the filter generation parameter which uses this annotation to include/exclude sections when generating documentation. For further details, see the help page for the filter parameter of AdeliaDoc call parameters.
Sections	Program/procedure
Parameters	Empty, or a list of labels (i.e. tags) separated by the "`;`" character
Markup	No
Notes	The `@adeliadoc` section in a program section is inherited by default by all its public procedures for which the `@adeliadoc` annotation has not been entered.
Examples	`@adeliadoc: internal;dev` `@adeliadoc: internal;` `@adeliadoc: premium_partners; internal` `@adeliadoc`

*@description

Role	Used to describe a section for the attention of the end user
Section	Program/procedure
Parameters	Description itself
Markup	Yes
Default value	Program description
Examples	On two lines, with the term unrecorded in bold: `@description: selection of an unrecorded* and active` `@\|item code.` With the addition of a link to the CLOSE_ORDER program documentation, via the Sphinx ":ref:" directive : `@description: This program should be used with :ref:'CLOSE_ORDER'`

*@param

Role	Used to describe a section parameter associated with instructions PARAM or RECEIVE.
Section	Program/procedure
Parameters	Four parameters in the following form: `<variable_name>, <input_output>, <variable_name_replaced_in_documentation>, <description>` `<variable_name>` : name of the 4GL variable associated with the parameter `<input_output>` : indicates whether it is an input, output or input/output parameter I : indicates that it is an input parameter `O` : indicates that it is an output parameter `B` : indicates that it is an input/output parameter `<variable_name_replaced_in_documentation>` : used to set a customized variable name which must be included in the documentation. If it is not entered, the name used in the 4GL source is included in the documentation. `<description>` : the variable description
Markup	Yes for the parameter `<description>`
Default value	In all cases, the generator uses the PARAM or RECEIVE instructions from the 4GL to produce or complete the documentation associated with the parameter by automatically generating the information relating to the type, length and size of the variable.
Notes	The first and last parameters are mandatory whereas the others are optional. This means that the annotation may contain only two parameters, the first and the last, in that order, separated by "`,`". When there is an optional parameter, all the other optional parameters must be entered. They can be presented as an empty string (or space) to show that they have no value entered. In all cases, and when appropriate, AdeliaDoc automatically generates information relating to the type, length and size of the parameter in the documentation. When a parameter refers to a class, AdeliaDoc automatically generates the documentation associated with the relevant class and adds a link to the parameter name thus enabling the user to directly access the relevant page.
Examples	Example with two parameters. The description of the first parameter will be presented in two separate lines: `ALPHA(20) PARAM2` `@param: PARAM1, ,DELIVERY_DATE, Product delivery` `@\|date (on an other line)` `@param: PARAM2,I,LABEL,Product title` `param PARAM1 PARAM2` Example with one parameter. The description of the first parameter will be presented in a single line `DATE PARAM1` `@param: PARAM1, ,DELIVERY_DATE, Product delivery` `@ date (on the same line)` `param PARAM1` Example with one parameter. The term "date" will be presented in bold: `DATE PARAM1` `@param: PARAM1,B,DELIVERY_DATE, Product delivery date` `param PARAM1`

*@field

Role	Describes a field associated with a previously annotated `List` type parameter.
Section	Program/procedure
Parameters	Three parameters in the following form: `<field_name>, <field_name_replaced_in_documentation>, <description>` `<field_name>` : name of the field variable associated with the "`List`" type parameter `<field_name_replaced_in_documentation>` : used to set a customized field variable name which must be included in the documentation. If it is not entered, the name used in the 4GL source is included in the documentation. `<description>` : field description
Markup	Yes for the parameter `<description>`
Default value	In all cases, the generator uses the `List` definition to produce or complete the documentation associated with the field by automatically generating the information relating to the type, length and size of the variable.
Notes	The first and last parameters are mandatory whereas the second is optional. `@field` annotations must follow the `@param` annotation of the "`List`" type parameter to which they refer, and in the declaration order in the list. In all cases, and when appropriate, AdeliaDoc automatically generates information relating to the type and length of the field in the documentation. When a parameter refers to a class, AdeliaDoc automatically generates the documentation associated with the relevant class and adds a link to the parameter name thus enabling the user to directly access the relevant page.
Example	Example of a list parameter with three fields: `ALPHA(20) MEMBER1` `ALPHA(200) MEMBER2` `DATE DEADLINE` `LIST SAMPLELIST MEMBER1 MEMBER2 MEMBER3` `@param: SAMPLELIST, I, TODOLIST, Tasks list` `@field: MEMBER1,TITLE, Task title` `@field: MEMBER2, DESCRIPTION, Task description` `@field: DEADLINE, Task deadline` `param SAMPLELIST`

*@version

Role	Indicates the section version number
Section	Program
Parameter	Version (free format)
Markup	No
Default value	Adelia object version
Example	`*@version: 11.3.6`

*@author

Role	Indicates the developer's name
Section	Program/procedure
Parameter	Developer's name
Markup	No
Default value	Name of Adelia object software engineer
Example	`*@author: Bill`

*@since

Role	Specifies the version since which the element was added.
Section	Program/procedure
Parameter	Relevant version (free format)
Markup	No
Default value	Not supported
Example	`*@since: 5.2.3.1`

*@date

Role	Indicates the date of the last section modification.
Section	Program/procedure
Parameter	Relevant date (free format)
Markup	No
Default value	Adelia object modification date
Notes	The use of this annotation in the documentation may not, in certain situations, correspond to the required behavior. That is why the date_annotation parameter in the configuration file can be used to force the default value (from the program information) in place of the entered parameter.
Example	*@date: 05/05/2021

*@deprecated

Role	Indicates that the entity is deprecated
Section	Program/procedure
Parameters	Two parameters in the following form: `<version>, <description>` `<version>` : version in which the section was deprecated `<description`> : explanatory comment
Markup	Yes for the <description> parameter
Default value	Not supported
Notes	AdeliaDoc uses the appropriate Sphinx directive to generate this annotation.
Examples	Version alone: `@deprecated: 3.1.5` Version with comment and formatting (bold and link): `@deprecated:3.1.5, use :ref :'TOOLBX.NEWUTIL' instead.`

*@index

Role	Used to index the section and describe the way it needs to appear in the global index of the documentation.
Section	Program/procedure
Parameters	Indexing values (see notes below)
Markup	No
Default value	Name of the object section
Notes	If two values are entered, separated by a "`;`", this is interpreted as an indexing hierarchy in the Sphinx Single sense (limited to a single hierarchy level). To define several different entries in the index for the same section, you need to enter: either several `@index` annotations in the section or several values separated by the "`,`" character in the same annotation `@index`
Examples	Definition of three index entries for a specific section: `@index: stock management, sales, purchase` Definition of two index entries for a specific section: `@index:receipt` `@index:returns` Definition of an index entry in hierarchy form with order* as the parent (if the order keyword itself corresponds to an index entry, it will be presented in the form of a hypertext link), along with a single entry: `@index:order;quote` `@index:how to make a quote`

↑ Top of page