Wie erstelle ich im Kernel Abschnitt 9 Manpages, die Funktionen, Datenstrukturen und Header dokumentieren?

Die Kernel - Quellen enthalten , Funktionen und Datenstrukturen , die dokumentiert sind, beispielsweise in 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, ...)

Anstatt jedes Mal die Quellen durchzugehen, wäre es nützlich, diese APIs als Manpages anzuzeigen und dieses vorhandene Dokumentationsframework zu nutzen.

Wie installiert / erstellt man die Kernel Section 9 Manpages ( /usr/share/man/man9), die die oben genannten Funktionen und Datenstrukturen dokumentieren?

kernel man documentation

— kakeh
quelle

Möchten Sie die von Ihnen verwendete Distribution teilen?

— Tink

Warum sind Sie sich so sicher, dass es für jede Version immer Manpages (insbesondere aktualisierte) gibt?

— mdpc

@ MDPC, warum nicht ein gut gepflegter Kernel keine Manpages haben wird, ich denke, meine Frage ist gültig

— Kakeh

"Sie müssen xmlto installieren" scheint der Startpunkt zu sein, nein?

— Braiam

@Bralam aktualisiert die Überraschung :(

— Kakeh

Antworten:

Der Inhalt wird direkt (siehe auch dies ) aus den Quell- C-Dateien ¹analysiert :

Um eine eingebettete, C-freundliche, leicht zu wartende, aber konsistente und extrahierbare Dokumentation der Funktionen und Datenstrukturen im Linux-Kernel bereitzustellen, hat der Linux-Kernel einen konsistenten Stil zur Dokumentation von Funktionen und deren Parametern sowie deren Strukturen und Strukturen übernommen Mitglieder.

Das Format für diese Dokumentation wird als Kernel-Doc-Format bezeichnet. Es ist in dieser Datei Documentation / kernel-doc-nano-HOWTO.txt dokumentiert.

Dieser Stil bettet die Dokumentation mit ein paar einfachen Konventionen in die Quelldateien ein. Das Skript / Kernel-Doc-Perl-Skript, einige SGML-Vorlagen in Documentation / DocBook und andere Tools verstehen diese Konventionen und werden verwendet, um diese eingebettete Dokumentation in verschiedene Dokumente zu extrahieren. [...]

Das Eröffnungskommentar "/ **" ist für Kernel-Doc-Kommentare reserviert. Nur so markierte Kommentare werden von den Kernel-Doc-Skripten berücksichtigt, und alle so markierten Kommentare müssen im Kernel-Doc-Format vorliegen.

Dies bedeutet, dass nur solche formatierten Kommentare auf diese Weise extrahiert werden können und dass Sie das vom Prozess verwendete Perl- Skript nutzen können:kernel-doc make

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

und deshalb, dass Sie nicht auf das Mandocs- Ziel beschränkt sind :

Nach der Installation wird die Dokumentation mit "psdocs erstellen", "pdfdocs erstellen", "htmldocs erstellen" oder "mandocs erstellen" im angeforderten Format gerendert.

Es gibt auch treiberspezifische Textdateien im Kernel-Repository / in der Quelle. Allgemeiner gesagt , ihr Linux - man-pages Projekt ( man1 durch man8 ist) verfügbar zum Download bereit . In einem letzten Hinweis verwaltet kernel.org auch einige Ausgabedokumentationen .

^{1. Der Kernel ist nicht der einzige Fall, in dem eine solche Technik zum Generieren von Manpages verwendet wird. GNU Coreutils ist ein solcher anderer Fall; Die meisten seiner Manpages werden mithilfe der Ausgabe des Inhalts generiert , dessen command --helpInhalt in der Verwendungsfunktion der Utility-Quelldatei ( 1 2 ) enthalten ist.}

— Gemeinschaft
quelle

make mandocs wirft michMakefile:19: /Documentation/DocBook/media/Makefile: No such file or directory

— kakeh

Ja, ich habe es, aber es Documentation/ist nicht in /seiner Gegenwart in/lib/modules/3.2.0-57-generic-pae/build/

— Kakeh

@Shyam Dies sind die Dateien für die Module usw., wie der Link zu Textdateien in meinem A. Sie können es vielleicht ./scripts/kernel-doc -man ./**/*.c >mydocim obersten Verzeichnis der Quellen versuchen und sehen, ob Sie nicht alle direkt in eine Datei einfügen können, indem Sie die Quellen direkt analysieren .

Angenommen, Sie verwenden Ubuntu.

apt-get install linux-manual-3.2

oder ähnlich (wählen Sie die richtige Version). Es gibt auch ein anderes Dokumentationspaket

apt-get install linux-doc

aber das ist html.

— Faheem Mitha
quelle

Dies zeigt nicht die Dokumentation von Kernel API

— Kakeh

@ Shyam Beispiel?

— Faheem Mitha

Auf Arch (Bang) habe ich: Linux-Manpages 3.14-1, die die Manpages von Abschnitt 9 enthalten! Danke! Ein Beispiel ist kcalloc.9.gz . Es gibt ungefähr 4000 von ihnen ...

@Faheem Mitha TREID die Betrachtungs man alloc_register_regionsagte aber keine manuelle Eingabe docs sind anders als man pages ??

— Kakeh

@FaheemMitha Ich glaube nicht, dass die Low-Level-APIs des Kernels mit Linux-Doc verfügbar sind!

— Kakeh

Laden Sie den Kernel-Quellcode herunter und führen Sie ihn im Quellverzeichnis aus

make mandocs

Nachdem die Manndokumente erstellt wurden, führen Sie sie aus

make installmandocs

Dadurch werden die Handbuchseiten in installiert /usr/local/man/man9/. Jetzt können Sie Manpages durch Eingabe anzeigen man <api-name>oder beim Bearbeiten vimeinfach Küber den API-Namen drücken .

— manav mn
quelle