Я написал небольшую C-библиотеку для Linux и FreeBSD и собираюсь написать документацию для нее. Я попытался узнать больше о создании man-страниц и не нашел инструкций или описаний лучших практик по созданию man-страниц для библиотек. В частности меня интересует, в какой раздел ставить man-страницы функций? 3? Может быть, есть хорошие примеры или руководства? Создавать man-страницы для каждой функции из библиотеки плохая идея?
Ответы:
Страницы справочника для библиотеки можно найти в разделе 3.
Для хороших примеров страниц руководства имейте в виду, что некоторые написаны с использованием конкретных деталей groff и / или используют конкретные макросы, которые на самом деле не переносимы.
В переносимости man-страниц всегда есть некоторые подводные камни, поскольку некоторые системы могут (или не могут) использовать специальные функции. Например, при документировании dialogмне приходилось учитывать (и обходить) различия в различных системах для отображения примеров (которые неоправданны).
Начните с чтения соответствующих разделов, man manгде упоминаются стандартные макросы, и сравните эти описания для FreeBSD и Linux.
Если вы решите написать одну справочную страницу для библиотеки или отдельные справочные страницы для функций (или групп функций), зависит от того, насколько сложным будет описание функций:
Дальнейшее чтение:
Я использую Ронна . Вы просто пишете уценку, и она превратится в справочную страницу. Там же (несколько менее способный) JS клон это называется разметкой люди .
Я документировал свои сценарии с помощью END_MANheredocs с разделителями и моего кода C / C ++ с использованием END_MANheredocs с разделителями, кроме как внутри /* */. Любой из них легко извлекается с помощью sed, а затем переводится в man-страницу. (Немного взломав сигнал UNIX вместе с inotifywait, вы можете извлекать и просматривать разделы вашей man-страницы в реальном времени и обновлять браузер man-страниц в качестве источника обновлений.)
Что касается раздела, то 3 будет для библиотеки уровня пользователя. Вы можете прочитать о номерах разделов (среди прочего) в man (1) .
Если вы хотите , чтобы увидеть некоторые читаемых, хорошо структурированы пример страницы человека, я беру бы взглянуть на Plan9 https://swtch.com/plan9port/unix/ библиотеки , где вы можете увидеть , как сами создатели cи UNIXи документацию Система, вероятно, предназначена для этих вещей, чтобы работать.
В дополнение к другим ответам, другим языком разметки, который можно использовать для упрощения написания man-страниц, является reStructuredText и команда rst2man, которая является частью пакета python-documentstils .
Этот язык разметки был принят python для его документации , и его гораздо легче изучать, писать и поддерживать, чем старые добрые макросы troff man, которые rst2man сгенерирует для вас из вашего reStructuredText.
Вы можете задокументировать API с помощью doxygen, чтобы предоставить ссылку в виде HTML, а также сгенерировать справочные страницы и другие форматы для чтения в автономном режиме.
Преимущество doxygen заключается в том, что это своего рода «встроенная» документация, такая как JavaDoc или PythonDoc, дублирующаяся как комментарии интерфейса (или vv., Комментарии дублирующиеся как текст документа); Вы добавляете документы в свои исходные / заголовочные файлы, и они извлекаются оттуда, что повышает шансы на актуальность.
manдля программирования кроме стандартной библиотеки и системных вызовов.