oRisDoc pour oRis 2.1

oRisDoc pour oRis 2.1

L'outil

oRisDoc est un outil entièrement écrit en oRis générant de manière automatique de la documentation en ligne, et ce uniquement à partir des déclarations de classes dans des fichiers pkg.

Pour générer l'aide, il faut dans un premier temps insérer devant chaque objet à documenter un bloc de commentaires, dans un format particulier. Une fois tout le code documenté, il suffit de lancer oRisDoc et celui-ci générera les fichiers dans le répertoire que vous lui aurez spécifié.

Format des blocs de commentaire

Les commentaires doivent être au format suivant :

/**
* Commentaire
* ...
* @motclé [paramètres]
* @motclé [paramètres]
* ...
*/
déclaration;

Les mots-clé valides sont :

@param Permet de commenter les paramètres d'une méthode.
Il doit exister pour chaque paramètre d'une méthode une entrée @param associée. L'ordre des paramètres correspond à l'ordre des mots-clé @param.

Syntaxe : @param commentaire du paramètre

@retour Permet de commenter la valeur de retour d'une méthode.
Si la méthode ne retourne pas de valeur (void), le mot-clé @retour ne doit pas apparaître dans le bloc de commentaire.

Syntaxe : @retour commentaire de la valeur de retour

@voir Permet d'indiquer que le lecteur de la documentation doit se reporter à une autre rubrique pour obtenir plus d'informations. Le lien est automatiquement mis en place en fonction du commentaire spécifié.

Syntaxe : @voir classe.methodeOuAttribut[,classe.methodeOuAttribut][...]
Si le paramètre classe n'est pas spécifié (le paramètre est alors du type .methodeOuAttribut), alors la méthode ou l'attribut indiqué sera cherché dans la classe actuelle.
Si le paramètre methodeOuAttribut n'est pas spécifié (le paramètre est alors du type classe), alors le lien pointera vers la documentation de la classe indiquée dans le paramètre classe.

@virtuel Indique que la déclaration suivant le bloc de commentaire sera mise également en commentaires, à l'aide de // ou de /* ... */.

Exemple :

/**
* Trie le contenu du tableau suivant la méthode spécifiée.
* @param méthode de tri à utiliser
* @retour le tableau trié
* @voir Tableau
*/
Tableau sort(int methode);

La ligne de commande

Syntaxe

oris -text orisdoc.ors [-batch] [-format format] [-destpath destpath] [-help | -h | -?] répertoire répertoire ...

Options

-batch Lance l'outil en mode automatique. La génération de la documentation se fait directement, sans afficher de boîte de dialogue de saisie de paramètres. Tous les paramètres utilisés sont soit les paramètres par défaut, soit les paramètres de la ligne de commande s'ils existent.

-format Format de la documentation générée. Actuellement, seuls les formats HTML et Plain sont reconnus.

-destpath Répertoire de destination des fichiers générés.

-language Langage utilisé lors de la génération. Actuellement, seuls les langages en pour l'anglais ou fr pour le français sont reconnus.

-help
-h
-? Affiche la syntaxe de la ligne de commande et quitte oRisDoc.

répertoire Répertoire contenant des fichiers d'extension pkg. Il peut y avoir autant de répertoires que nécessaire.

@param	Permet de commenter les paramètres d'une méthode. Il doit exister pour chaque paramètre d'une méthode une entrée @param associée. L'ordre des paramètres correspond à l'ordre des mots-clé @param. Syntaxe : @param commentaire du paramètre
@retour	Permet de commenter la valeur de retour d'une méthode. Si la méthode ne retourne pas de valeur (void), le mot-clé @retour ne doit pas apparaître dans le bloc de commentaire. Syntaxe : @retour commentaire de la valeur de retour
@voir	Permet d'indiquer que le lecteur de la documentation doit se reporter à une autre rubrique pour obtenir plus d'informations. Le lien est automatiquement mis en place en fonction du commentaire spécifié. Syntaxe : @voir classe.methodeOuAttribut[,classe.methodeOuAttribut][...] Si le paramètre classe n'est pas spécifié (le paramètre est alors du type .methodeOuAttribut), alors la méthode ou l'attribut indiqué sera cherché dans la classe actuelle. Si le paramètre methodeOuAttribut n'est pas spécifié (le paramètre est alors du type classe), alors le lien pointera vers la documentation de la classe indiquée dans le paramètre classe.
@virtuel	Indique que la déclaration suivant le bloc de commentaire sera mise également en commentaires, à l'aide de // ou de /* ... */.

-batch	Lance l'outil en mode automatique. La génération de la documentation se fait directement, sans afficher de boîte de dialogue de saisie de paramètres. Tous les paramètres utilisés sont soit les paramètres par défaut, soit les paramètres de la ligne de commande s'ils existent.
-format	Format de la documentation générée. Actuellement, seuls les formats HTML et Plain sont reconnus.
-destpath	Répertoire de destination des fichiers générés.
-language	Langage utilisé lors de la génération. Actuellement, seuls les langages en pour l'anglais ou fr pour le français sont reconnus.
-help -h -?	Affiche la syntaxe de la ligne de commande et quitte oRisDoc.
répertoire	Répertoire contenant des fichiers d'extension pkg. Il peut y avoir autant de répertoires que nécessaire.