¿Cómo hacer las páginas de manual de la sección 9 del núcleo que documentan funciones, estructuras de datos y encabezados?

Las fuentes del núcleo contienen funciones y estructuras de datos que están documentadas, por ejemplo en panic.c:

/**
 *  panic - halt the system
 *  @fmt: The text string to print
 *
 *  Display a message, then perform cleanups.
 *
 *  This function never returns.
 */
void panic(const char *fmt, ...)

En lugar de revisar las fuentes cada vez, sería útil ver esas API como páginas de manual y aprovechar este marco de documentación existente.

¿Cómo se instala / crea las páginas de manual ( /usr/share/man/man9) de la sección 9 del núcleo que documentan las funciones y estructuras de datos mencionadas anteriormente?

El contenido se analiza directamente (consulte también esto ) desde los archivos .c de origen ¹ :

Para proporcionar documentación incrustada, amigable con 'C', fácil de mantener, pero consistente y extraíble de las funciones y estructuras de datos en el kernel de Linux, el kernel de Linux ha adoptado un estilo consistente para documentar funciones y sus parámetros, estructuras y sus miembros.

El formato para esta documentación se llama formato kernel-doc. Está documentado en este archivo Documentation / kernel-doc-nano-HOWTO.txt.

Este estilo incorpora la documentación dentro de los archivos fuente, usando algunas convenciones simples. Los scripts / kernel-doc perl script, algunas plantillas SGML en Documentation / DocBook y otras herramientas entienden estas convenciones y se utilizan para extraer esta documentación incrustada en varios documentos. [...]

La marca de comentario de apertura "/ **" está reservada para los comentarios de kernel-doc. Los scripts kernel-doc solo considerarán los comentarios marcados de esta manera, y cualquier comentario marcado de este modo debe estar en formato kernel-doc.

Lo que significa que solo dichos comentarios formateados se pueden extraer de esta manera y que podría aprovechar el script Perl utilizado por el proceso:kernel-doc make

kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]
  [ -no-doc-sections ]
  [ -function funcname [ -function funcname ...] ]
  c file(s)s > outputfile

y, por lo tanto, que no está limitado al objetivo de mandocs :

Después de la instalación, "make psdocs", "make pdfdocs", "make htmldocs" o "make mandocs" mostrarán la documentación en el formato solicitado.

También hay archivos de texto específicos del controlador en el repositorio / fuente del kernel. En términos más generales, su proyecto de páginas de manual de Linux ( man1 a man8 ) está disponible para descargar. En una última nota, kernel.org también mantiene cierta documentación de salida .

^{1. El núcleo no es el único caso en el que se utiliza dicha técnica para generar páginas de manual. GNU coreutils es otro de esos casos; La mayoría de sus páginas de manual se generan utilizando la salida del command --helpcontenido del cual está en la función de uso el archivo fuente de la utilidad ( 1 2 ).}

Asumiendo que estás usando Ubuntu,

apt-get install linux-manual-3.2

o similar (elija la versión correcta). También hay otro paquete de documentación.

apt-get install linux-doc

Pero esto es HTML.

Descargue el código fuente del kernel y en el directorio fuente ejecute

make mandocs

Después de que se hayan realizado los documentos man, ejecute

make installmandocs

Esto instalará las páginas del manual en /usr/local/man/man9/. Ahora puede ver las páginas man escribiendo man <api-name>, o si está editando vimsimplemente presione Ksobre el nombre de la API.