Products Downloads


French version


 

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 and Event 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 and Event 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).


AnnotationRole
*@adeliadocUsed to label (i.e. tag) a section in order to apply filter rules when producing documentation.
*@descriptionSection description
*@paramSection parameter description
*@fieldDescription of a field associated with a "List" type parameter
*@versionIndicates a section's version
*@authorName of section developer
*@sinceIndicates which version the section has been added since
*@dateDate of last section modification
*@deprecatedIndicates that the section is deprecated
*@indexUsed 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.

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



  • Aucune étiquette