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.

Program/procedure

• Empty,

• or a list of labels (i.e. tags) separated by the ";" character

No

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.

• *@adeliadoc: internal;dev

• *@adeliadoc: internal;

• *@adeliadoc: premium_partners; internal

• *@adeliadoc

Used to describe a section for the attention of the end user

Program/procedure

Description itself

Yes

Program description

• 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'

Used to describe a section parameter associated with instructions PARAM or RECEIVE.

Program/procedure

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

Yes for the parameter <description>

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.

• 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.

• 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

Describes a field associated with a previously annotated List type parameter.

Program/procedure

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

Yes for the parameter <description>

In all cases, the generator uses the Liste 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.

• 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 of a list parameter with three fields:

ALPHA(20) MEMBER1

ALPHA(200) MEMBER2

DATE DEADLINE

LISTE 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

Indicates the section version number

Program

Version (free format)

No

Adelia object version

*@version: 11.3.6

Indicates the developer's name

Program/procedure

Developer's name

No

Name of Adelia object software engineer

*@author: Bill

Specifies the version since which the element was added.

Program/procedure

Relevant version (free format)

No

Not supported

*@since: 5.2.3.1

Indicates the date of the last section modification.

Program/procedure

Relevant date (free format)

No

Adelia object modification date

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.

*@date: 05/05/2021

Indicates that the entity is deprecated

Program/procedure

Two parameters in the following form: <version>, <description>

• <version> : version in which the section was deprecated

• <description> : explanatory comment

Yes for the <description> parameter

Not supported

AdeliaDoc uses the appropriate Sphinx directive to generate this annotation.

• Version alone:
  *@deprecated: 3.1.5

• Version with comment and formatting (bold and link):
  *@deprecated:3.1.5, **use** :ref :'TOOLBX.NEWUTIL' instead.

Used to index the section and describe the way it needs to appear in the global index of the documentation.

Program/procedure

Indexing values (see notes below)

No

Name of the object section

• 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

• 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