Loading AI tools
Un générateur de documentation est un outil de programmation qui crée de la documentation destinée aux programmeurs (il s'agit alors d'une documentation d'API) ou aux utilisateurs finaux (il s'agit alors d'un guide d'utilisateur) ou encore les deux. Pour gérer ces documentations, le générateur se base généralement sur des codes sources commentés d'une certaine façon et dans certains cas également sur des fichiers binaires.
Cet article est une ébauche concernant l’informatique.
Vous pouvez partager vos connaissances en l’améliorant (comment ?) selon les recommandations des projets correspondants.
La documentation générée peut être hautement technique, et est principalement utilisée pour définir et expliquer les interfaces de programmation (APIs), les structures de données et les algorithmes. Par exemple, on peut utiliser cette documentation pour expliquer que la variable m_name se réfère au premier et au dernier nom d'une personne. Il est important pour les documents sur le code d'être précis, mais pas non plus verbeux à un point tel qu'il serait difficile de les maintenir.
Les générateurs de documentation tels que Sphinx, doxygen ou javadoc génèrent automatiquement la documentation à partir du code source. Ils extraient le commentaire du code source et créent des manuels de référence sous des formats comme le texte, des fichiers HTML, PDF, DocBook, ou RTF. Les documents sur le code sont souvent organisés dans le style d'un guide de référence, ce qui permet à un programmeur de localiser rapidement une fonction ou une classe quelconque.
L'avantage d'un générateur de documentation à partir du code source est la proximité du code source avec sa documentation codée sous forme de commentaires. Le programmeur peut alors l'écrire en se référant à son code, et peut utiliser les mêmes outils que ceux qu'il a utilisés pour développer le code source, pour faire la documentation. Cela rend beaucoup plus facile la mise à jour de la documentation.
Bien sûr, l'inconvénient est que seuls les programmeurs peuvent éditer cette sorte de documentation, et c'est d'eux que dépend la mise à jour des sorties (par exemple, en exécutant un crontab pour mettre à jour les documents la nuit). Certains pourraient caractériser cela comme un avantage plutôt que comme un inconvénient.
Voici un exemple de documentation de code source Java, qui peut être extrait par javadoc :
/**
* Valider un mouvement de jeu d'échecs.
*
* @param colonneDepart Colonne de la case de départ de la pièce à déplacer.
* @param ligneDepart Ligne de la case de départ de la pièce à déplacer.
* @param colonneArrivee Colonne de la case de destination.
* @param ligneArrivee Ligne de la case de destination.
* @return vrai(true) si le mouvement d'échec est valide ou faux(false) si invalide.
*/
boolean estUnDéplacementValide(int colonneDepart, int ligneDepart,
int colonneArrivee, int ligneArrivee)
{
/* ... */
}
Équivalent avec le générateur Doxygen :
/**
* Valider un mouvement de jeu d'échecs.
*
* @param colonneDepart Colonne de la case de départ de la pièce à déplacer.
* @param ligneDepart Ligne de la case de départ de la pièce à déplacer.
* @param colonneArrivee Colonne de la case de destination.
* @param ligneArrivee Ligne de la case de destination.
* @return Validité du mouvement d'échec.
* @retval vrai(true) Mouvement d'échec valide.
* @retval faux(false) Mouvement d'échec invalide.
*/
int estUnDéplacementValide(int colonneDepart, int ligneDepart,
int colonneArrivee, int ligneArrivee)
{
// ...
}
Variante avec le générateur Doxygen :
/**
* @brief Valider un mouvement de jeu d'échecs.
* @return Validité du mouvement d'échec.
* @retval vrai(true) Mouvement d'échec valide.
* @retval faux(false) Mouvement d'échec invalide.
*/
int estUnDéplacementValide
(
//! Colonne de la case de départ de la pièce à déplacer.
int colonneDepart,
//! Ligne de la case de départ de la pièce à déplacer.
int ligneDepart,
//! Colonne de la case de destination.
int colonneArrivee,
//! Ligne de la case de destination.
int ligneArrivee)
{
// ...
}
Un autre exemple de commentaire, pour le générateur mkd:
/*D
ExitError
-----------------------------------------------------------------------------
ACTION:
Affiche l'erreur dans une fenêtre en version console et quitte
la fonction en renvoyant la valeur -1 à la fonction appelante.
Affiche l'erreur dans une fenêtre d'erreur en version fenêtrée.
SYNTAXE:
#include <CmapGpsu.h>
int ExitError(int iErr);
PORTABILITE:
x86 Win32_Console MS-Windows ; UNICODE
DESCRIPTION:
int iErr : Numéro d'erreur à transcrire en clair au terminal ou à la
fenêtre d'affichage d'erreur en version fenêtrée.
VALEUR RETOURNEE:
Quitte le programme CmapGpsu et renvoie la valeur -1 au programme
appelant.
*/
/*H // ExitErr.c:
extern int ExitError(int iErr);
*/
L'option d'extraction D extraira la documentation de la fonction. Le document final contiendra la documentation de l'ensemble des fonctions dans l'ordre alphabétique. Le contenu extrait peut être écrit dans tous langages tels XML, HTML, etc.
L'option H extraira la déclaration de la fonction qui sera intégrée dans le fichier d'entête des fonctions du programme, ici, dans cmapgpsu.h
- Docutils [1] avec son célèbre format ReStructuredText, plutôt pour Python
- Doxygen (multilangage, surtout ceux de la famille C)
- FORD[2] pour le langage Fortran.
- Javadoc, outil de génération de documentation pour le langage Java, développé par Sun
- MakeDoc (REBOL 2000)
- mkd[3]ex makedoc sous UNIX (multilangage, 1994) a repris son nom originel de 1990 en raison de son homonymie avec de nouveaux logiciels comme MakeDoc, MakeDocu etc.
- OCamlDoc, outil de génération de documentation pour le langage OCaml, développé par l'INRIA;
- POD (Perl)
- RDoc (Ruby)
- ROBODoc (multilangage, y compris les plus courants, mais il peut être aussi étendu[4])
- roxygen[5] pour le langage R
- SandCastle, outil de génération de documentation pour les langages .Net, édité par Microsoft
- Sphinx, outil de génération de documentation pour le langage Python, développé par la Python Software Foundation;
- TwinText (multilangage, y compris les plus courants, mais il peut être aussi étendu[6])
- Visdoc, outil de génération de documentation HTML pour le langage ActionScript 2 (AS2) & 3 (AS3) et Java (MAC uniquement)
- XMLDoc, outil open source de génération de documentation pour les langages .Net (en cours de développement)
- Doctum, outil open source de génération de documentation pour les projets php
Wikiwand in your browser!
Seamless Wikipedia browsing. On steroids.
Every time you click a link to Wikipedia, Wiktionary or Wikiquote in your browser's search results, it will show the modern Wikiwand interface.
Wikiwand extension is a five stars, simple, with minimum permission required to keep your browsing private, safe and transparent.
