Eu escrevi uma pequena biblioteca C para Linux e FreeBSD e vou escrever a documentação para isso. Tentei aprender mais sobre a criação de páginas de manual e não encontrei as instruções ou descrições de práticas recomendadas para criar páginas de manual para bibliotecas. Em particular, estou interessado em qual seção colocar páginas de manual das funções? 3? Talvez haja bons exemplos ou manuais? Criar páginas de manual para cada função da biblioteca é uma má idéia?
12
manpara programação, exceto biblioteca padrão e syscalls.Respostas:
As páginas de manual de uma biblioteca aparecerão na seção 3.
Para bons exemplos de páginas de manual, lembre-se de que alguns são escritos usando detalhes específicos do groff e / ou usam macros específicas que não são realmente portáteis.
Sempre existem algumas armadilhas na portabilidade das páginas de manual, pois alguns sistemas podem (ou não) usar recursos especiais. Por exemplo, na documentação
dialog, eu tive que ter em mente (e contornar) as diferenças em vários sistemas para exibir exemplos (que não são justificados).Comece lendo as seções relevantes de
man manonde ele menciona as macros padrão e compare essas descrições para FreeBSD e Linux.A escolha de escrever uma página de manual para a biblioteca ou separar páginas de manual para as funções (ou grupos de funções) depende de quão complicadas as descrições das funções seriam:
Leitura adicional:
fonte
Eu uso ronn . Você simplesmente escreve o markdown, e isso o transforma em uma página de manual. Há também um clone js (um tanto menos capaz) chamado homem marcado .
Eu tenho documentado meus scripts usando
END_MANheredocs delimitados e meu código C / C ++ usando os mesmosEND_MANheredocs delimitados, exceto dentro/* */. Qualquer um é facilmente extraível com sed e depois renderizável em uma página de manual. (Com um pouco de invasão de sinal do UNIX junto com o inotifywait, você pode extrair e exibir suas seções de páginas de manual ao vivo e fazer com que o navegador de páginas de manual seja recarregado conforme a fonte é atualizada.)Quanto à seção, 3 seria para uma biblioteca C em nível de usuário. Você pode ler sobre os números de seção (entre outras coisas) em man (1) .
Se você quiser ver algumas, exemplo páginas man legíveis bem estruturados, eu tomaria um olhar para o Plan9 https://swtch.com/plan9port/unix/ bibliotecas onde você pode ver como os próprios criadores
ceUNIXe sua documentação sistema provavelmente destinado a essas coisas funcionarem.fonte
Para complementar as outras respostas, outra linguagem de remarcação que pode ser usada para simplificar a escrita de páginas de manual é reStructuredText e o comando rst2man, que faz parte do pacote python-docutils .
Essa linguagem de remarcação foi adotada pelo python para sua documentação e é muito mais fácil aprender, escrever e manter do que as boas e antigas macros do troff man que o rst2man irá gerar para você a partir do seu reStructuredText.
fonte
Você pode documentar a API usando doxygen para fornecer a referência como HTML e também gerar páginas de manual e outros formatos para leitura offline.
A vantagem do doxygen é que é uma espécie de documentação "em linha", como JavaDoc ou PythonDoc, dobrando como comentários de interface (ou vv., Comentários dobrando como texto de documento); você adiciona os textos do documento aos arquivos de origem / cabeçalho e é extraído a partir daí, o que aumenta as chances de atualização.
fonte