| dbo:abstract
|
- Un générateur de documentation est un 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. 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. (fr)
- Un générateur de documentation est un 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. 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. (fr)
|
