Jak zrobić strony podręcznika sekcji 9 jądra, które dokumentują funkcje, struktury danych i nagłówki?

Źródła jądra zawierają funkcje i struktury danych, które są udokumentowane, na przykład w 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, ...)

Zamiast za każdym razem przeglądać źródła, przydatne byłoby przeglądanie tych interfejsów API jako stron podręcznika i wykorzystanie istniejącej struktury dokumentacji.

W jaki sposób instalujesz / tworzysz sekcję 9 manpages ( /usr/share/man/man9) dotyczącą jądra, która dokumentuje wyżej wymienione funkcje i struktury danych?

Zawartość jest analizowana bezpośrednio (patrz także to ) ze źródłowych plików .c ¹ :

Aby zapewnić osadzoną, przyjazną dla języka C, łatwą w utrzymaniu, ale spójną i możliwą do wyodrębnienia dokumentację funkcji i struktur danych w jądrze Linux, jądro Linux przyjęło spójny styl dokumentowania funkcji i ich parametrów oraz struktur i ich członkowie.

Format tej dokumentacji nazywa się formatem kernel-doc. Jest to udokumentowane w tym pliku Documentation / kernel-doc-nano-HOWTO.txt.

Ten styl osadza dokumentację w plikach źródłowych, stosując kilka prostych konwencji. Skrypty / skrypt kernel-doc perl, niektóre szablony SGML w Documentation / DocBook oraz inne narzędzia rozumieją te konwencje i są używane do wyodrębnienia tej osadzonej dokumentacji do różnych dokumentów. [...]

Znak komentarza otwierającego „/ **” jest zarezerwowany dla komentarzy jądra-doc. Tylko komentarze oznaczone w ten sposób będą rozpatrywane przez skrypty kernel-doc, a każdy tak oznaczony komentarz musi być w formacie kernel-doc.

Co oznacza, że ​​tylko takie sformatowane komentarze można wyodrębnić w ten sposób i że można wykorzystać skrypt Perla używany przez proces:kernel-doc make

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

i dlatego nie jesteś ograniczony do celu mandoc :

Po instalacji „make psdocs”, „make pdfdocs”, „make htmldocs” lub „make mandocs” renderują dokumentację w żądanym formacie.

Istnieją również pliki tekstowe specyficzne dla sterownika w repozytorium / źródle jądra. Mówiąc bardziej ogólnie, ich projekt stron man Linuxa (od man1 do man8 ) jest dostępny do pobrania. W ostatniej notatce kernel.org prowadzi również dokumentację wyjściową .

^{1. Jądro nie jest jedynym przypadkiem, w którym taka technika jest używana do generowania stron podręcznika. Coreutils GNU to jeden z takich przypadków; większość jego stron jest generowanych przy użyciu danych wyjściowych, command --helpktórych zawartość jest w funkcji użycia źródłowym pliku narzędziowym ( 1 2 ).}

Zakładając, że używasz Ubuntu,

apt-get install linux-manual-3.2

lub podobny (wybierz odpowiednią wersję). Istnieje również inny pakiet dokumentacji

apt-get install linux-doc

ale to jest HTML.

Pobierz kod źródłowy jądra i uruchom katalog źródłowy

make mandocs

Po utworzeniu dokumentów man wykonaj polecenie

make installmandocs

Spowoduje to zainstalowanie stron podręcznika w /usr/local/man/man9/. Teraz możesz przeglądać strony podręcznika man <api-name>, pisząc lub, jeśli edytujesz, po vimprostu naciśnij Knazwę interfejsu API.