Comment créer les pages de manuel de la section 9 du noyau qui documentent les fonctions, les structures de données et les en-têtes?

Les sources du noyau contiennent des fonctions et des structures de données qui sont documentées, par exemple dans 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, ...)

Au lieu de parcourir les sources à chaque fois, il serait utile de visualiser ces API comme des pages de manuel et de tirer parti de ce cadre de documentation existant.

Comment installer / créer les pages de manuel de la section 9 du noyau ( /usr/share/man/man9) qui documentent les fonctions et les structures de données susmentionnées?

Le contenu est analysé directement (voir aussi ceci ) à partir des fichiers source .c ¹ :

Afin de fournir une documentation intégrée, conviviale en «C», facile à entretenir, mais cohérente et extractible des fonctions et des structures de données dans le noyau Linux, le noyau Linux a adopté un style cohérent pour documenter les fonctions et leurs paramètres, et les structures et leurs membres.

Le format de cette documentation est appelé le format kernel-doc. Il est documenté dans ce fichier Documentation / kernel-doc-nano-HOWTO.txt.

Ce style intègre la documentation dans les fichiers source, en utilisant quelques conventions simples. Le script perl scripts / kernel-doc, certains modèles SGML dans Documentation / DocBook et d'autres outils comprennent ces conventions et sont utilisés pour extraire cette documentation intégrée dans divers documents. [...]

La marque de commentaire d'ouverture "/ **" est réservée aux commentaires de documentation du noyau. Seuls les commentaires ainsi marqués seront pris en compte par les scripts kernel-doc, et tout commentaire ainsi marqué devra être au format kernel-doc.

Ce qui signifie que seuls ces commentaires formatés peuvent être extraits de cette façon et que vous pouvez tirer parti du script Perl utilisé par le processus:kernel-doc make

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

et donc que vous n'êtes pas limité à la cible mandocs :

Après l'installation, "make psdocs", "make pdfdocs", "make htmldocs" ou "make mandocs" rendra la documentation dans le format demandé.

Il existe également des fichiers texte spécifiques au pilote dans le référentiel / source du noyau. Plus généralement, leur projet de pages de manuel Linux ( man1 à man8 ) est disponible en téléchargement. Sur une dernière note, kernel.org conserve également une documentation de sortie .

^{1. Le noyau n'est pas le seul cas où une telle technique est utilisée pour générer des pages de manuel. GNU coreutils est un de ces autres cas; la plupart de ses pages de manuel sont générées en utilisant la sortie dont command --helple contenu est dans la fonction d' utilisation le fichier source de l'utilitaire ( 1 2 ).}

En supposant que vous utilisez Ubuntu,

apt-get install linux-manual-3.2

ou similaire (choisissez la bonne version). Il existe également un autre package de documentation

apt-get install linux-doc

mais c'est html.

Téléchargez le code source du noyau et exécutez-le dans le répertoire source

make mandocs

Une fois les documents de l'homme créés, exécutez

make installmandocs

Cela installera les pages de manuel dans /usr/local/man/man9/. Vous pouvez maintenant afficher les pages de manuel en tapant man <api-name>, ou si vous modifiez en appuyant vimsimplement Ksur le nom de l'API.