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 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, en documentant dialog , j'ai dû garder à l'esprit (et contourner) les différences entre les différents systèmes d'affichage des exemples (qui ne sont pas justifiés).
Commencez par lire les sections pertinentes de man man où il mentionne les macros standard, et comparer ces descriptions pour FreeBSD et Linux.
Que vous choisissiez d'écrire une page de manuel pour la bibliothèque ou des pages de manuel séparées 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 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 -- affiche les pages de documentation du manuel en ligne (FreeBSD)
- man-pages - conventions d'écriture des pages de manuel Linux
- groff_mdoc -- référence pour l'implémentation mdoc de groff
- HowTo :Créer une page de manuel à partir de zéro. (FreeBSD)
- Qu'est-ce qu'un "abri à vélos" ?
J'utilise ronn. Vous écrivez simplement Markdown, et cela le transformera en une page de manuel. Il y a aussi un js (un peu moins capable) clone de celui-ci appelé homme-marqué.
J'ai documenté mes scripts avec en utilisant END_MAN délimité heredocs et mon code C/C++ en utilisant le même END_MAN délimité icidocssauf entre /* */ . L'un ou l'autre est facilement extractible avec sed puis rendu dans une page de manuel. (Avec un peu de piratage des signaux UNIX et inotifywait, vous pouvez extraire et afficher les sections de votre page de manuel en direct et recharger le navigateur de la page de manuel au fur et à mesure que les sources sont mises à jour. )
En ce qui concerne la section, alors 3 le serait pour une bibliothèque C de niveau utilisateur. Vous pouvez en savoir plus sur 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, je jetterais un coup d'œil aux bibliothèques Plan9 https://swtch.com/plan9port/unix/ où vous pouvez voir comment les créateurs mêmes de c et UNIX et son système de documentation probablement destiné à faire fonctionner ces choses.
Pour compléter les autres réponses, un autre langage de démarquage qui peut être utilisé pour simplifier l'écriture des pages de manuel est reStructuredText et la commande rst2man qui fait partie de python-docutils forfait.
Ce langage de démarquage 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 va générer pour vous à partir de votre reStructuredText.