Информационное пространство: документирование

Информационное пространство:

Источники информации:

Информационное пространство в совместной разработке

Это опять на целый С/К

Техническое документирование: Doxygen

Cайт

Пример:

Итак, возьмём наш старый проект по генерации фентезийных имён namegen и добавим в него документацию

  1. Создаём шаблон doxygen -g Doxyfile.in (он будет обрабатывается autoconf)

  2. Настраиваем этот шаблон (включаем фичи, подставляем макросы)
  3. Переоформляем комментарии согласно дисциплине Doxygen
    • у Doxygen есть понятие «документация к файлу» (@file)

    • у Doxygen есть понятие «главная страница»
  4. Включаем поддержку Doxygen а autotools
  5. Настраиваем генерацию других документов (например, man)

  6. Сборка документации запускается по умолчанию

Документирование: Sphinx

Вообще-то Sphinx намного современнее Doxygen, а единственное дополнительное требование — это Python и его модули.

Но универсальных инструментов ∃ примерно два, и про Sphinx есть в курсе «Совместная разработка приложений на Python»

Man

Варианты написания man-страницы:

Man и --help

Мы попробуем убить двух зайцев: написать --help к некоторой программе и обработать это с помощью help2man (соответствующий пакет следует поставить).

Кстати, help2man — в действительности программа для изготовления man-страницы «на скорую руку». В ней по умолчанию предполагается, что у проекта есть «полноценная» документация в формате texinfo, но это отдельная тема…

Д/З

  1. Поизучать пример (можно любой другой, например, старый вариант ☺)

  2. Взять за основу программу для угадывания чисел из старого Д/З

    • Дописать к ней две функции — перевод из римской системы счисления и обратно
      • Поскольку диапазон 1…100, проще всего сделать табличку на 100 элементов, ну не знаю, при помощи roman, :)

    • Научить саму программу принимать из командной строки параметр -r для работы в римской системе счисления

    • Задокументировать эти функции (и, возможно, другие, буде они у вас есть), а так же макросы и глобальные переменные (которые сочтёте нужными)
    • Обеспечить программе вменяемый --help (на двух языках!) и man (на одном)

    • Заполнить этим help-ом титульную страницу документации
  3. Некоторые подробности
    • Титульную страничку придётся генерировать чем-то боле сложным, чем LC_ALL=C ./number-game --help. Например, научить саму программу чему-то вроде --help-md (в который она подставляет команды Doxygen) или обработать --hеlp чем-то ещё

      • Если ничего не поможет, забейте и тупо скопируйте. Ну не будет у вас титульная страница генератом, возможно, начнёт расходиться с --help и man, и что?

    • <!> (необязательно, для тех, кто хочет поупражняться программировать на Си) Увеличить диапазон до 1…3999

  4. Положить всё это хозяйство в подкаталог 11_Documenting отчётного репозитория

LecturesCMC/LinuxApplicationDevelopment2023/11_Documenting (последним исправлял пользователь Veniamin 2023-12-01 17:13:47)