Dois-je écrire des pages de manuel pour la bibliothèque C?

J'ai écrit une petite bibliothèque C pour Linux et FreeBSD, et je vais écrire la documentation pour cela. J'ai essayé d'en savoir plus sur la création de pages de manuel et je n'ai pas trouvé les instructions ou les descriptions des meilleures pratiques pour créer des pages man pour les bibliothèques. En particulier, je suis intéressé par quelle section mettre les pages man des fonctions? 3? Peut-être de bons exemples ou des manuels? Créer des pages man pour chaque fonction de la bibliothèque une mauvaise idée?

Les pages de manuel d'une bibliothèque iraient dans la section 3.

Pour de bons exemples de pages de manuel, gardez à l'esprit que certaines sont écrites en utilisant des détails spécifiques de groff et / ou utilisent des macros spécifiques qui ne sont pas vraiment portables.

Il y a toujours quelques pièges dans la portabilité des pages de manuel, puisque certains systèmes peuvent (ou ne peuvent pas) utiliser des fonctionnalités spéciales. Par exemple, dans le dialog documentation, j'ai dû garder à l'esprit (et contourner) les différences dans les différents systèmes pour afficher des exemples (qui ne sont pas justifiés).

Commencez par lire les sections pertinentes de man man où il mentionne les macros standard, et comparez ces descriptions pour FreeBSD et Linux.

Que vous choisissiez d'écrire une page de manuel pour la bibliothèque ou des pages de manuel distinctes pour les fonctions (ou groupes de fonctions) dépend de la complexité des descriptions des fonctions:

  • ncurses a quelques centaines de fonctions sur plusieurs dizaines de pages de manuel.
  • dialog comporte plusieurs dizaines de fonctions dans une page de manuel. D'autres seront sûrs de montrer beaucoup plus d'exemples.

Pour en savoir plus:

  • man – affiche des pages de documentation manuelle en ligne (FreeBSD)
  • man-pages – conventions pour écrire des pages de manuel Linux
  • groff_mdoc – reference pour la mise en œuvre de mdoc de groff
  • Comment: créer une page de manuel à partir de zéro. (FreeBSD)
  • Qu'est-ce qu'un "Bikeshed"?

J'utilise ronn . Vous écrivez simplement markdown, et il va en faire une page de manuel. Il y a aussi un clone js (un peu less capable) appelé mark-man .

J'ai documenté mes scripts en utilisant des END_MAN délimités par END_MAN et mon code C / C ++ en utilisant les mêmes END_MAN délimités END_MAN sauf dans /* */ . Soit facilement extractible avec sed puis rendu dans une page de manuel. (Avec un peu de hackery de signal UNIX avec inotifywait, vous pouvez extraire et afficher vos sections de manpage en direct et faire recharger le browser de la page man lorsque la source se met à jour.)

Comme pour la section, alors 3 serait-il pour une bibliothèque C au niveau de l'user. Vous pouvez lire sur les numéros de section (entre autres) dans l' homme (1) .

Si vous voulez voir des exemples de pages de manuel bien structurées, je jetterais un coup d'œil aux bibliothèques Plan9 https://swtch.com/plan9port/unix/ où vous pouvez voir comment les créateurs de c et UNIX et son système de documentation probablement destiné à ces choses à travailler.

Pour compléter les autres réponses, un autre langage de démarque qui peut être utilisé pour simplifier l'écriture des pages de manuel est reStructuredText et la command rst2man qui fait partie du packageage python-docutils .

Ce langage de démarque a été adopté par python pour sa documentation , et il est beaucoup plus facile à apprendre, à écrire et à maintenir que les macros bon vieux troff man que rst2man va générer pour vous à partir de votre reStructuredText.

Vous pouvez documenter l'API à l'aide de Doxygen pour fournir la reference au format HTML, et générer également des pages man et d'autres formats pour la lecture hors ligne.

L'avantage de Doxygen est qu'il s'agit d'une sorte de documentation "inline" comme JavaDoc ou PythonDoc, doublant en tant que commentaires d'interface (ou vv., Doublage de commentaires en tant que text doc); vous ajoutez les texts doc à vos files source / en-tête, et il est extrait de là, ce qui améliore les chances d'être tenu à jour.