Escribí una pequeña biblioteca C para Linux y FreeBSD, y voy a escribir la documentación para ello. Traté de aprender más sobre la creación de páginas de manual y no encontré las instrucciones o descripciones de las mejores prácticas para crear páginas de manual para bibliotecas. En particular, estoy interesado en qué sección poner páginas de manual de las funciones. 3? Tal vez hay buenos ejemplos o manuales? Crear páginas de manual para cada función de la biblioteca ¿es una mala idea?
12
manpara la programación, excepto la biblioteca estándar y las llamadas al sistema.Respuestas:
Las páginas de manual para una biblioteca irían en la sección 3.
Para obtener buenos ejemplos de páginas del manual, tenga en cuenta que algunas están escritas usando detalles específicos de groff y / o usan macros específicas que no son realmente portátiles.
Siempre hay algunas dificultades en la portabilidad de las páginas de manual, ya que algunos sistemas pueden (o no) usar características especiales. Por ejemplo, al documentar
dialog, he tenido que tener en cuenta (y evitar) las diferencias en varios sistemas para mostrar ejemplos (que no están justificados).Comience leyendo las secciones relevantes de
man mandonde menciona las macros estándar y compare 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:
Otras lecturas:
fuente
Yo uso ronn . Simplemente escriba Markdown, y lo convertirá en una página de manual. También hay un clon js (algo menos capaz) llamado marcado .
He estado documentando mis scripts con él usando
END_MANheredocs delimitados y mi código C / C ++ usando los mismosEND_MANheredocs delimitados excepto dentro/* */. Cualquiera de los dos es fácilmente extraíble con sed y luego renderizable 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 sobre los números de sección (entre otras cosas) en man (1) .
Si quieres ver algunos ejemplos de páginas man legibles, bien estructurados, me gustaría echar un vistazo a la Plan9 https://swtch.com/plan9port/unix/ bibliotecas donde se puede ver cómo los mismos creadores de
cyUNIXy su documentación sistema probablemente destinado a que estas cosas funcionen.fuente
Para complementar las otras respuestas, otro lenguaje de descuento que se puede utilizar para simplificar la escritura de páginas de manual es reStructuredText y el comando rst2man que forma parte del paquete python-docutils .
Python adoptó este lenguaje de rebajas para su documentación , y es mucho más fácil de aprender, escribir y mantener que las buenas y viejas macros de troff man que rst2man generará para usted a partir de su texto reStructuredText.
fuente
Puede documentar la API utilizando doxygen para proporcionar la referencia como HTML, y también generar páginas de manual y otros formatos para lectura fuera de línea.
La ventaja de doxygen es que es una especie de documentación "en línea" como JavaDoc o PythonDoc, que se duplica como comentarios de interfaz (o vv., Los comentarios se duplican como texto de documento); agrega los textos del documento a sus archivos de origen / encabezado, y se extrae de allí, lo que mejora las posibilidades de mantenerse actualizado.
fuente