Detailed description of annotationsIn 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. Info |
---|
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'.
|
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)
*@adeliadocRole | 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 | |
---|
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 | |
---|
*@descriptionRole | 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'
|
---|
*@paramRole | 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
|
---|
*@fieldRole | Describes a field associated with a previously annotated Liste 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 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. |
---|
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
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
|
---|
*@versionRole | Indicates the section version number |
---|
Section | Program |
---|
Parameter | Version (free format) |
---|
Markup | No |
---|
Default value | Adelia object version |
---|
Example | *@version: 11.3.6
|
---|
*@authorRole | 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
|
---|
*@sinceRole | 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
|
---|
*@dateRole | 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 |
---|
*@deprecatedRole | Indicates that the entity is deprecated |
---|
Section | Program/procedure |
---|
Parameters | Two parameters in the following form: <version>, <description> |
---|
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.
|
---|
*@indexRole | 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 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
|
---|
|