7.3. Генераторы документации
Очевидным способом объединения документации и программного кода является подробное комментирование программного кода. При внесении изменений в программу имеется возможность сразу же обновить документирующие поведение программы комментарии в коде. Существуют инструменты, позволяющие автоматически извлечь из файла программы специальным образом оформленные комментарии и оформить результат в виде справочной документации по программному модулю.
Примеры генераторов документации:
- Javadoc для языка Java;
- Doxygen для C++ и некоторых других языков;
- Расширения для системы Sphinx, поддерживающие целый ряд языков.
Ниже показан пример программы на языке C со специальными комментариями, поддерживаемыми системой Doxygen. Обратите внимание на специальные ключевые слова \file, \brief и \param:
/// \file main.cpp
/// Модуль main.
#include <stdio.h>
/// \brief Главная функция.
/// \param int argc Счетчик аргументов.
/// \param char **argv Указатель на аргументы.
int main(int argc, char **argv) {
return 0;
}
Далее приведен пример программы на языке Питон, с комментариями, поддерживаемыми системой Sphinx. Обратите внимание на специальные ключевые слова param, type и return:
"""
Модуль main.
"""
def main(x, y):
"""
Функция main.
:param x: Параметр x.
:type x: str
:param y: Параметр y.
:type y: int
:return: Ничего не возвращает.
"""