Як зробити манжети розділу 9 ядра, які функціонують із документами, структурами даних та заголовками?

Джерела ядра містять функції та структури даних, які задокументовані, наприклад у 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, ...)

Замість того, щоб щоразу переглядати джерела, було б корисно розглядати ці API як підручники та використовувати цю існуючу документаційну структуру.

Як встановити / зробити манежі розділу 9 ядра ( /usr/share/man/man9), які документують вищезазначені функції та структури даних?

Вміст аналізується безпосередньо (див. Також це ) з вихідних файлів .c ¹ :

Для того, щоб забезпечити вбудовану "C" зручну, просту в обслуговуванні, але послідовну та витягувану документацію функцій та структур даних у ядрі Linux, ядро ​​Linux прийняло послідовний стиль документування функцій та їх параметрів, структур та їх члени.

Формат цієї документації називається форматом kernel-doc. Це задокументовано у цьому документі / kernel-doc-nano-HOWTO.txt-файл.

Цей стиль вбудовує документацію у вихідні файли, використовуючи кілька простих конвенцій. Сценарії сценаріїв / kernel-doc perl, деякі шаблони SGML в Documentation / DocBook та інші інструменти розуміють ці умови, і вони використовуються для вилучення цієї вбудованої документації в різні документи. [...]

Вступний знак коментаря "/ **" зарезервований для коментарів ядра-doc. Лише так помічені коментарі будуть розглядатися сценаріями ядра-doc, а будь-який коментар, такий маркований, повинен бути у форматі kernel-doc.

Що означає, що лише такі відформатовані коментарі можуть бути вилучені таким чином, і ви можете використовувати сценарій Perl, який використовується процесом:kernel-doc make

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

і , отже, ви не обмежені mandocs мети :

Після встановлення "make psdocs", "make pdfdocs", "make htmldocs" або "make mandocs" нададуть документацію у потрібному форматі.

Також у сховищі / джерелі ядра є певні текстові файли . В цілому, їх Linux проект людино-сторінки ( man1 через man8 ) є доступний для скачування. На останній ноті kernel.org також підтримує деяку вихідну документацію.

^{1. Ядро - не єдиний випадок, коли така методика використовується для генерації manpages. GNU coreutils - це ще один такий випадок; більшість його mangeges генеруються за допомогою виведення command --helpвмісту, який знаходиться у функції використання, файл джерела утиліти ( 1 2 ).}

Припустимо, що ви використовуєте Ubuntu,

apt-get install linux-manual-3.2

або подібне (виберіть правильну версію). Також є ще один пакет документів

apt-get install linux-doc

але це html.

Завантажте вихідний код ядра та виконайте його у dir-файлі

make mandocs

Після того, як чоловік зробив документи, виконайте

make installmandocs

Це дозволить встановити сторінки вручну /usr/local/man/man9/. Тепер ви можете переглядати основні сторінки, набравши текст man <api-name>, або якщо ви редагуєте, vimпросто натисніть Kім'я API.