Téléchargement des produits


Version anglaise


 

Généralités

Lorsqu'ils commentent le code source, les développeurs Adélia peuvent signaler qu'un commentaire doit être intégré dans la documentation technique à l'aide d'une syntaxe dédiée appelée "annotation".


Selon les types de programmes, les annotations doivent être insérées à un endroit spécifique du code source :

  • Pour les programmes Visual : qu'il s'agisse d'un programme, d'une procédure ou d'une règle de gestion, les annotations doivent impérativement être placées dans les blocs de déclaration (DECL PGM/DECLARATION), avant l'utilisation de l'ordre PARAM.

  • Pour les programmes Adelia : par souci de lisibilité, les annotations doivent être placées en début de source, et dans tous les cas avant l'ordre RECEVOIR.

  • Pour les classes : les annotations ne sont pas supportées dans les sources des classes.

    Néanmoins, pour les classes référencées dans des programmes Visual, AdeliaDoc exploite l'option de classe et d'attribut *SER_DESC pour insérer une description personnalisée lors de la génération de la documentation de la classe.

Syntaxe

L'ensemble des annotations AdeliaDoc répondent aux même règles de syntaxe, telles que décrites ci-dessous :

  • Une annotation est constituée d'un mot clé, et d'un ou plusieurs paramètres.
  • Un mot clé commence toujours par le digramme "*@".
  • Le caractère ":" est utilisé comme séparateur entre le mot clé et les paramètres ; des caractères "blanc" peuvent éventuellement précéder et succéder le caractère séparateur.
  • Le caractère "," est utilisé comme séparateur de paramètres ; il est déconseillé d'insérer des caractères " blanc " avant ou après le caractère séparateur.
  • Un mot clé n'est pas sensible à la casse, mais ses paramètres oui.
  • Une annotation doit impérativement figurer en début de ligne (il est cependant possible de la faire précéder de caractères " blanc " ou "tabulation" ).
  • Les paramètres d'annotation correspondant à des descriptions textuelles peuvent être saisis sur plusieurs lignes, dans ce cas :
    • le digramme "*@" devra marquer le début de la nouvelle ligne,
    • s'il s'agit de conserver la mise en forme multiligne dans le support, le trigramme "*@|" devra dans ce cas marquer le début de la nouvelle ligne.
  • Exemples :
    • Annotation simple avec un paramètre :
      *@deprecated : 3.2.5

    • Annotation avec un un paramètre multiligne - dans cet exemple, la description apparaîtra sous la forme de deux lignes dans le support de documentation :
      *@description : Sélection d'un code article non consigné.
      *@|Le paramètre P_DISP_ALL doit être initialisé à la valeur 0
      *@pour filtrer sur les articles non consignés et actifs.
      Résultat obtenu dans la documentation : 

      Sélection d'un code article non consigné.
Le paramètre P_DISP_ALL doit être initialisé à la valeur 0 pour filtrer sur les articles non consignés et actifs.

↑ Haut de page

Tableau descriptif des annotations supportées

Chacune des annotations référencées ci-dessous peut être utilisée indifféremment dans un bloc de déclaration de programme ou de procédure.

Dans la suite de ce document, le terme de " section " est utilisé pour faire référence à de tels blocs (pour rappel, dans le cas des programmes de type Adélia, les annotations doivent être saisies en début de programme, avant l'ordre RECEVOIR).


AnnotationRôle
*@adeliadoc Permet d'étiqueter (i.e. taguer) une section afin de pouvoir appliquer des règles de filtrage lors de la production de la documentation
*@description Description de la section
*@param Description d'un paramètre de section
*@field Description d'un champ associé à un paramètre de type "Liste"
*@version Indique la version d'une section
*@author Nom du développeur de la section
*@since Indique depuis quelle version la section a été ajoutée
*@date Date de dernière modification de la section
*@deprecated Indique que la section est dépréciée
*@index Permet d'ajouter une entrée d'index associée à la section dans l'index global de la documentation


Il est entendu que toutes les annotations sont optionnelles. En sachant que pour une section donnée, lorsqu'une partie ou la totalité des annotations attendues n'ont pas été saisies, quand cela est possible, et si le paramétrage d'AdeliaDoc l'autorise, des valeurs par défaut issues de l'analyse du source et des informations de description des programmes Adélia sont utilisées en lieu et place pour produire la documentation.

Description détaillée des annotations

Dans la suite du document :

  • le terme "markup" indique qu'il est possible d'utiliser certains éléments de la syntaxe reStructuredText ou certains rôles Sphinx pour mettre en forme un contenu textuel, et principalement pour ajouter des liens vers d'autres sections de la documentation.
    Il est néanmoins fortement déconseillé de faire un usage intensif et inapproprié d'éléments de mise en forme, en sachant que la bonne restitution dans la documentation produite ne peut être totalement garantie. 

    Dans le cadre de l'ajout de liens hypertexte, AdeliaDoc impose une codification particulière pour identifier les sections, qu'il est nécessaire de respecter si vous souhaitez utiliser le rôle ":ref:" ad hoc :

    • Identification d'une section programme : l'identifiant est le nom du programme lui-même.

      *@description: ce programme correspond à une déclinaison du calcul de marge par rapport à la version proposée dans le programme :ref:'COMPUTE_PROFIT'.

    • Identification d'une section procédure : l'identifiant est la concaténation du nom du programme et du nom de la procédure sous la forme PROGRAM.PROC.

      *@description: ce programme correspond à une déclinaison du calcul de marge par rapport à la version proposée dans la procédure :ref:'COMMONSPROCS.PROC_PROFIT'.

    • Identification d'une section classe : l'identifiant de la classe s'exprime de la façon suivante : class_CLASSNAME :

      *@description: ce programme utilise la classe :ref:'class_ORDER' pour créer une commande.

  • La notion de "valeur par défaut" correspond à la provenance de la donnée de substitution lorsque l'annotation correspondante n'a pas été renseignée par le développeur (en tenant compte des règles de substitution issues des paramètres de configuration d'AdeliaDoc)

*@adeliadoc

Rôle

Permet d'étiqueter (i.e. taguer) une section afin notamment d 'identifier des catégories de public visés.

En lien direct avec le paramètre de génération filter , qui exploite cette annotation pour inclure/exclure des sections lors de la génération d'une documentation.

Pour plus de détails, reportez-vous à la page d'aide du paramètre filter des paramètres d'appel AdeliaDoc.

Sections

Programme/procédure

Paramètres

  • Vide,

  • ou bien une liste d'étiquettes (i.e. tags) , séparées par le caractère ";"

Markup

Non

Remarques

L'annotation *@adeliadoc au niveau d'une section programme est héritée par défaut par toutes ses procédures publiques pour lesquelles l'annotation *@adeliadoc n'aurait pas été renseignée.

Exemples

  • *@adeliadoc: internal;dev

  • *@adeliadoc: internal;

  • *@adeliadoc: premium_partners; internal

  • *@adeliadoc


*@description

Rôle

Permet de décrire une section à l'attention de l'utilisateur final

Section

Programme/procédure

Paramètres

Description elle-même

Markup

Oui

Valeur par défaut

Désignation du programme

Exemples

  • Sur deux lignes, avec mise en gras du terme unrecorded :
    *@description: selection of an **unrecorded** and active
    *@|item code.

  • Avec ajout d'un lien vers la page de documentation du programme CLOSE_ORDER , via la directive Sphinx ":ref:" :
    *@description: This program should be used
    with :ref:'CLOSE_ORDER'


*@param

Rôle

Permet de décrire un paramètre de section, associé aux ordres PARAM ou RECEVOIR.

Section

Programme/procédure

Paramètres

Quatre paramètres sous la forme : <nom_variable>, <entrée_sortie>, <nom_variable_substituée_dans_documentation>, <description>

  • <nom_variable> : nom de la variable L4G associée au paramètre

  • <entrée_sortie> : permet d'indiquer si il s'agit d'un paramètre en entrée, en sortie, ou en entrée/sortie

    • I : indique qu'il s'agit d'un paramètre en entrée

    • O : indique qu'il s'agit d'un paramètre en sortie

    • B : indique qu'il s'agit d'un paramètre en entrée/sortie

  • <nom_variable_substituée_dans_documentation> : permet de fixer un nom personnalisé de la variable, devant figurer dans la documentation. Si non renseigné, c'est le nom utilisé dans le source L4G qui est restitué dans la documentation.

  • <description> : la description de la variable

Markup

Oui pour le paramètre <description>

Valeur par défaut

Dans tous les cas, le générateur exploite les ordres PARAM ou RECEVOIR du L4G pour produire ou compléter la documentation associée au paramètre, en générant automatiquement les informations relatives au type, à la longueur et aux dimensions de la variable.

Remarques

  • Le premier et le dernier paramètre sont obligatoires, les deux autres sont facultatifs.

  • Ce qui signifie que cette annotation peut contenir uniquement deux paramètres, le premier et le dernier, dans cet ordre, séparés par ","

  • A partir du moment où figure un paramètre optionnel, l'ensemble des autres paramètres optionnels doivent être renseignés, avec la possibilité de les faire figurer sous forme de chaîne vide (ou espace), pour signifier qu'ils ne sont pas valorisés.

  • Dans tous les cas, et quand cela a un sens, AdeliaDoc génère automatiquement dans la documentation les informations relatives au type, à la longueur et aux dimensions du paramètre.

  • Dans le cas d'un paramètre faisant référence à une classe, AdeliaDoc génère automatiquement la documentation associée à la classe en question, et enrichit le nom du paramètre avec un lien, permettant ainsi à l'utilisateur d'accéder directement à la page en question.

Exemples

  • Exemple avec deux paramètres. La description du premier paramètre sera présentée sur 2 lignes distinctes :

    ALPHA(20) PARAM2

    *@param: PARAM1, ,DELIVERY_DATE, Product delivery
    *@|date (on an other line)
    *@param: PARAM2,I,LABEL,Product title
    param PARAM1 PARAM2


  • Exemple avec un paramètre. La description du premier paramètre sera présentée sur une seule ligne

    DATE PARAM1

    *@param: PARAM1, ,DELIVERY_DATE, Product delivery
    *@ date (on the same line)
    param PARAM1


  • Exemple avec un paramètre. Le terme "date" sera présentée en gras :

    DATE PARAM1
    *@param: PARAM1,B,DELIVERY_DATE, Product delivery **date**
    param PARAM1


*@field

Rôle

Permet de décrire un champ associé à un paramètre de type Liste précédemment annoté.

Section

Programme/procédure

Paramètres

Trois paramètres sous la forme : <nom_champ>, <nom_champ_substitué_dans_documentation>, <description>

  • <nom_champ> : nom de la variable champ associée au paramètre de type Liste

  • <nom_champ_substitué_dans_documentation> : permet de fixer un nom personnalisé de la variable champ, devant figurer dans la documentation. Si non renseigné, c'est le nom utilisé dans le source L4G qui est restitué dans la documentation.

  • <description> : description du champ

Markup

Oui pour le paramètre <description>

Valeur par défaut

Dans tous les cas, le générateur exploite la définition de la Liste pour produire ou compléter la documentation associé e au champ, en générant automatiquement les informations relatives au type, à la longueur et aux dimensions de la variable.

Remarques

  • Le premier et le dernier paramètre sont obligatoires, le deuxième est facultatif.

  • Les annotations *@field doivent absolument suivre l'annotation *@param du paramètre de type "Liste" auquel elles se référent, et dans l'ordre de déclaration dans la liste.

  • Dans tous les cas, et quand cela a un sens, AdeliaDoc génère automatiquement dans la documentation les informations relatives au type et à la longueur du champ.

  • Dans le cas d'un paramètre faisant référence à une classe, AdeliaDoc génère automatiquement la documentation associée à la classe en question, et enrichit le nom du paramètre avec un lien, permettant ainsi à l'utilisateur d'accéder directement à la page en question.

Exemple

Exemple d'un paramètre liste avec trois champs :

ALPHA(20) MEMBER1

ALPHA(200) MEMBER2

DATE DEADLINE

LISTE 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

Rôle

Indique le numéro de version de la section

Section

Programme

Paramètre

Version (format libre)

Markup

Non

Valeur par défaut

Version de l'objet Adelia

Exemple

*@version: 11.3.6


*@author

Rôle

Indique le nom du développeur

Section

Programme/procédure

Paramètre

Nom du développeur

Markup

Non

Valeur par défaut

Nom du concepteur de l'objet Adélia

Exemple

*@author: Bill


*@since

Rôle

Permet de préciser depuis quelle version l'élément a été ajouté.

Section

Programme/procédure

Paramètre

Version en question (format libre)

Markup

Non

Valeur par défaut

Non supportée

Exemple

*@since: 5.2.3.1


*@date

Rôle

Permet d'indiquer la date de dernière modification de la section.

Section

Programme/procédure

Paramètre

Date en question (format libre)

Markup

Non

Valeur par défaut

Date de modification de l'objet Adélia

Remarques

L'utilisation et l'exploitation de cette annotation dans la documentation pourrait, dans certaines situations, ne pas correspondre au comportement souhaité.

C'est pourquoi le paramètre date_annotation du fichier de configuration permet de forcer la valeur par défaut (issue des informations du programme), en lieu et place du paramètre saisi.

Exemple

*@date: 05/05/2021


*@deprecated

Rôle

Permet d'indiquer que l'entité est dépréciée

Section

Programme/procédure

Paramètres

Deux paramètres sous la forme : <version>, <description>

  • <version> : version à partir de laquelle la section a été dépréciée

  • <description> : commentaire explicatif

Markup

Oui pour le paramètre <description>

Valeur par défaut

non supportée

Remarques

AdeliaDoc utilise la directive Sphinx idoine pour générer cette annotation.

Exemples

  • Version seule :
    *@deprecated: 3.1.5

  • Version avec commentaire et mise en forme (gras et lien) :
    *@deprecated:3.1.5, **use** :ref :'TOOLBX.NEWUTIL' instead.


*@index

Rôle

Permet d'indexer la section et de qualifier la façon doit elle doit apparaître dans l'index global de la documentation.

Section

Programme/procédure

Paramètres

Valeurs d'indexation (cf. les remarques ci-dessous)

Markup

Non

Valeur par défaut

Nom de l'objet section

Remarques

  • Si deux valeurs sont saisies, séparées par un ";", cela est interprété comme une hiérarchie d'indexage au sens Single de Sphinx (limité à un seul niveau de hiérarchie).

  • Pour définir plusieurs entrées différentes dans l'index pour la même section, il faut saisir :

    • soit plusieurs annotations *@index dans la section

    • soit plusieurs valeurs séparées par le caractère "," dans une même annotation *@index

Exemples

  • Définition des trois entrées d'index pour une section donnée :
    *@index: stock management, sales, purchase


  • Définition de deux entrées d'index pour une section donnée :

    *@index:receipt

    *@index:returns


  • Définition d'une entrée d'index sous forme hiérarchique avec comme père order (si le mot clé order correspond lui-même à une entrée d'index, il sera présenté sous la forme d'un lien hypertexte), doublé d'une entrée simple :

    *@index:order;quote
    *@index:how to make a quote





↑ Haut de page



  • Aucune étiquette