Las páginas del manual para una biblioteca irían en la sección 3.
Para obtener buenos ejemplos de páginas de manual, tenga en cuenta que algunas están escritas con detalles específicos de groff y/o usan macros específicas que no son realmente portátiles.
Siempre hay algunas trampas en la portabilidad de las páginas de manual, ya que algunos sistemas pueden (o no) usar funciones especiales. Por ejemplo, al documentar dialog , tuve que tener en cuenta (y solucionar) las diferencias en varios sistemas para mostrar ejemplos (que no están justificados).
Comience leyendo las secciones relevantes de man man donde menciona las macros estándar y comparar esas descripciones para FreeBSD y Linux.
Si elige escribir una página de manual para la biblioteca o páginas de manual separadas para las funciones (o grupos de funciones) depende de cuán complicadas sean las descripciones de las funciones:
- ncurses tiene unos pocos cientos de funciones en varias docenas de páginas de manual.
- diálogo tiene varias docenas de funciones en una página de manual. Otros se asegurarán de mostrar muchos más ejemplos.
Lectura adicional:
- man -- muestra las páginas de documentación del manual en línea (FreeBSD)
- man-pages - convenciones para escribir páginas man de Linux
- groff_mdoc -- referencia para la implementación de mdoc de groff
- Cómo:crear una página de manual desde cero. (FreeBSD)
- ¿Qué es un "cobertizo para bicicletas"?
Yo uso ron. Simplemente escriba markdown, y lo convertirá en una página de manual. También hay un (algo menos capaz) js clon de él llamado hombre marcado.
He estado documentando mis scripts usando END_MAN heredocs delimitados y mi código C/C++ usando el mismo END_MAN delimitado heredocsexcept dentro de /* */ . Cualquiera de los dos se puede extraer fácilmente con sed y luego se puede representar en una página de manual. (Con un poco de piratería de señales UNIX junto con inotifywait, puede extraer y ver las secciones de su página de manual en vivo y hacer que el navegador de la página de manual se vuelva a cargar a medida que se actualiza la fuente).
En cuanto a la sección, entonces 3 sería para una biblioteca C de nivel de usuario. Puede leer acerca de los números de sección (entre otras cosas) en man(1).
Si desea ver algunas páginas de manual de ejemplo legibles y bien estructuradas, echaría un vistazo a las bibliotecas de Plan9 https://swtch.com/plan9port/unix/ donde puede ver cómo los mismos creadores de c y UNIX y su sistema de documentación probablemente pretendía que estas cosas funcionaran.
Para complementar las otras respuestas, otro lenguaje de rebajas que se puede usar para simplificar la escritura de páginas man es reStructuredText y el comando rst2man que es parte de python-docutils paquete.
Este lenguaje de rebajas ha sido adoptado por python para su documentación, y es mucho más fácil de aprender, escribir y mantener que las viejas macros de troff man que rst2man generará para usted a partir de su reStructuredText.