Я написав невелику бібліотеку С для Linux та FreeBSD, і я збираюся написати документацію на це. Я спробував дізнатися більше про створення довідкових сторінок і не знайшов інструкцій чи описів найкращих практик створення довідкових сторінок для бібліотек. Зокрема, мене цікавить, у який розділ розмістити підручні сторінки функцій? 3? Можливо, є хороші приклади чи посібники? Створити підручні сторінки для кожної функції з бібліотеки погана ідея?
Відповіді:
Сторінки керівництва для бібліотеки пройдуть у розділі 3.
Для наглядних прикладів сторінок вручну майте на увазі, що деякі з них написані з використанням конкретних деталей groff та / або використання конкретних макросів, які насправді не є портативними.
Завжди є деякі підводні камені в переносимості підручних сторінок, оскільки деякі системи можуть (або не можуть) використовувати спеціальні функції. Наприклад, під час документування dialogмені довелося мати на увазі (і обійти) відмінності в різних системах для відображення прикладів (які не є виправданими).
Почніть з читання відповідних розділів, man manде згадуються стандартні макроси, та порівняйте ці описи для FreeBSD та Linux.
Незалежно від того, чи ви вирішите написати одну сторінку керівництва для бібліотеки, або окремі сторінки керівництва для функцій (або групи функцій), залежить від того, наскільки складними будуть описи функцій:
Подальше читання:
Я використовую ronn . Ви просто напишіть відмітку, і це перетворить це на сторінку. Також є (дещо менш здібний) клон js його, який називається позначеною людиною .
Я документував свої сценарії з ним, використовуючи END_MANрозмежовані гередоки та мій код C / C ++, використовуючи ті самі END_MANобмежені гередоки, за винятком усередині /* */. Або легко витягується з sed і потім передається в manpage. (Маючи трохи хакерського сигналу UNIX разом із inotifywait, ви можете витягувати та переглядати розділи маніпуляцій у прямому ефірі та перезавантажувати браузер manpage у міру оновлення джерела.)
Що стосується розділу, то 3 це буде для бібліотеки С на рівні користувача. Про номери розділів (серед іншого) можна прочитати у людині (1) .
Якщо ви хочете , щоб побачити деякі читаються, добре структуровані приклад сторінки людини, я беру б поглянути на Plan9 https://swtch.com/plan9port/unix/ бібліотеки , де ви можете побачити , як самі творці cі UNIXта документацію Система, ймовірно, призначена для цих речей.
Щоб доповнити інші відповіді, ще однією мовою розмітки, яка може бути використана для спрощення написання довідкових сторінок, є reStructuredText та команда rst2man, яка є частиною пакету python-docutils .
Ця мова розмітки була прийнята python для її документації , і її набагато простіше вивчати, писати та підтримувати, ніж старі добрі макроси man-troff man, які rst2man буде генерувати для вас із вашого reStructuredText.
Ви можете документувати API, використовуючи doxygen, щоб надати посилання як HTML, а також генерувати довідкові сторінки та інші формати для читання в режимі офлайн.
Перевага доксигену полягає в тому, що це така собі "вбудована" документація, як JavaDoc або PythonDoc, подвоєння як коментарі інтерфейсу (або vv., Коментарі подвоєні як текст документа); ви додаєте тексти doc до своїх вихідних / заголовкових файлів, і вони витягуються звідти, що покращує шанси бути актуальними.
manдля програмування, крім стандартної бібліотеки та системних дзвінків.