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 en écrire la documentation. 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 de création de pages de manuel pour les bibliothèques. En particulier, je suis intéressé par quelle section mettre les pages de manuel des fonctions? 3? Peut-être y a-t-il de bons exemples ou manuels? Créer des pages de manuel pour chaque fonction de la bibliothèque une mauvaise idée?

Les pages de manuel pour 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 existe toujours des pièges dans la portabilité des pages de manuel, car certains systèmes peuvent (ou non) utiliser des fonctionnalités spéciales. Par exemple, dans la documentation dialog, j'ai dû garder à l'esprit (et contourner) les différences entre les différents systèmes d'affichage d'exemples (qui ne sont pas justifiés).

Commencez par lire les sections pertinentes de l' man manendroit 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.
• La boîte de dialogue a plusieurs dizaines de fonctions dans une seule page de manuel. D'autres ne manqueront pas de montrer de nombreux autres exemples.

Lectures complémentaires:

• man - afficher les pages de documentation du manuel en ligne (FreeBSD)
• pages de manuel - conventions pour l'écriture de pages de manuel Linux
• groff_mdoc - référence pour l'implémentation mdoc de groff
• HowTo: Créez une page de manuel à partir de zéro. (FreeBSD)
• Qu'est-ce qu'un "Bikeshed"?

J'utilise ronn . Vous écrivez simplement Markdown, et cela le transformera en une page de manuel. Il y a aussi un clone js (un peu moins capable) appelé marqué-man .

J'ai documenté mes scripts avec en utilisant des END_MANheredocs délimités et mon code C / C ++ en utilisant les mêmes END_MANheredocs délimités, sauf à l'intérieur /* */. L'un ou l'autre est facilement extractible avec sed, puis rendu dans une page de manuel. (Avec un peu de piratage de signaux UNIX avec inotifywait, vous pouvez extraire et afficher vos sections de page de manuel en direct et faire recharger le navigateur de page de manuel en tant que mises à jour source.)

Quant à la section, alors 3 le serait pour une bibliothèque C de niveau utilisateur. Vous pouvez lire les numéros de section (entre autres) dans man (1) .

Si vous voulez voir des exemples de pages de manuel lisibles et bien structurées, j'aimerais jeter un œil aux bibliothèques Plan9 https://swtch.com/plan9port/unix/ où vous pouvez voir comment les créateurs mêmes de cet UNIXet sa documentation système probablement destiné à ce que ces choses fonctionnent.

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 commande rst2man qui fait partie du paquet python-docutils .

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

Vous pouvez documenter l'API à l'aide de doxygen pour fournir la référence au format HTML, et également générer des pages de manuel et d'autres formats pour une lecture hors ligne.

L'avantage de doxygen est qu'il s'agit d'une sorte de documentation "en ligne" comme JavaDoc ou PythonDoc, doublée en tant que commentaires d'interface (ou vv., Commentaires doublant en tant que texte doc); vous ajoutez les textes de doc à vos fichiers source / en-tête, et ils sont extraits de là, ce qui améliore les chances d'être tenu à jour.