Como tornar a seção 9 do kernel páginas de manual que documentam funções, estruturas de dados e cabeçalhos?

As fontes do kernel contêm funções e estruturas de dados que estão documentadas, por exemplo 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, ...)

Em vez de procurar as fontes todas as vezes, seria útil visualizar essas APIs como páginas de manual e aproveitar essa estrutura de documentação existente.

Como você instala / cria a seção 9 do kernel, manpages ( /usr/share/man/man9), que documenta as funções e estruturas de dados acima mencionadas?

O conteúdo é analisado diretamente (veja também isso ) dos arquivos .c de origem ¹ :

Para fornecer documentação incorporada, amigável ao C, fácil de manter, mas consistente e extraível das funções e estruturas de dados no kernel Linux, o kernel Linux adotou um estilo consistente para documentar funções e seus parâmetros, estruturas e seus membros.

O formato para esta documentação é chamado de formato kernel-doc. Está documentado neste arquivo Documentação / kernel-doc-nano-HOWTO.txt.

Esse estilo incorpora a documentação nos arquivos de origem, usando algumas convenções simples. O script scripts / kernel-doc perl, alguns modelos SGML na Documentação / DocBook e outras ferramentas compreendem essas convenções e são usados ​​para extrair essa documentação incorporada em vários documentos. [...]

A marca de comentário de abertura "/ **" está reservada para comentários do kernel-doc. Somente comentários marcados serão considerados pelos scripts do kernel-doc, e qualquer comentário marcado deve estar no formato do kernel-doc.

O que significa que apenas esses comentários formatados podem ser extraídos dessa maneira e que você pode aproveitar o script Perl usado pelo processo:kernel-doc make

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

e, portanto, você não está limitado ao destino mandocs :

Após a instalação, "make psdocs", "make pdfdocs", "make htmldocs" ou "make mandocs" renderizarão a documentação no formato solicitado.

Também existem arquivos de texto específicos do driver no repositório / fonte do kernel. Mais geralmente, o seu projecto-homem páginas Linux ( man1 através man8 ) é disponível para download. Em uma última nota, o kernel.org também mantém alguma documentação de saída .

^{1. O kernel não é o único caso em que essa técnica é usada para gerar páginas de manual. GNU coreutils é outro caso; a maioria de suas páginas de manual é gerada usando a saída command --helpcujo conteúdo está na função de uso , no arquivo de origem do utilitário ( 1 2 ).}

Supondo que você esteja usando o Ubuntu,

apt-get install linux-manual-3.2

ou similar (escolha a versão correta). Há também outro pacote de documentação

apt-get install linux-doc

mas isso é html.

Faça o download do código fonte do kernel e no diretório source execute

make mandocs

Depois que os documentos do homem forem feitos, execute

make installmandocs

Isso instalará as páginas de manual no /usr/local/man/man9/. Agora você pode visualizar as páginas de manual digitando man <api-name>ou, se estiver editando, vimpressione Ko nome da API.