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

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

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

Инструменты интерактивной совместной разработки

Должна быть отдельная лекция, но успеем ли?

Doxygen

Cайт

Пример:

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

Sphinx

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

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

Man и --help

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

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

Д/З

  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/LinuxApplicationDevelopment2021/11_Documenting (последним исправлял пользователь FrBrGeorge 2021-12-11 17:26:58)