Ответ 1
Существует множество разных стандартов, если вы хотите создать документацию, попробуйте doxygen
Как написать комментарии к документации в ANSI C?
Я не могу найти, как писать комментарии в C. Я имею в виду, что знаю о // и /* */, я имею в виду, где я могу найти хорошие практики? Как если бы у меня была функция, как написать @param variable is the value bla bla, как это делается в Java?
Существуют ли какие-либо стандарты для этого? Или я могу просто сделать это, как я делаю это на Java?
Ответы
Ответ 2
Стандарты не соответствуют стандарту, который соответствует вашей компании.
Популярным способом создания документации из проектов является использование Doxygen.
Ответ 3
Вы можете использовать стандарт javadoc, а затем использовать doxygen, который понимает javadoc для создания документации.
В doxygen я рекомендую использовать параметр JAVADOC_AUTOBRIEF для YES. Если для тега JAVADOC_AUTOBRIEF установлено значение YES, то doxygen интерпретирует первую строку (до первой точки) комментария стиля в стиле Javadoc как краткое описание.
Пример определения класса:
/**
* A brief description. A more elaborate class description
* @param bool somebool a boolean argument.
* @see Test()
* @return The test results
*/
(Еще несколько примеров в руководстве doxygen)
Установка действительно проста, есть графический интерфейс и хорошая графическая визуализация, доступная с помощью
apt-get install doxygen doxygen-gui graphviz
Запустите gui-вызов doxywizard и используйте настройки мастера, только JAVADOC_AUTOBRIEF необходимо установить там в настройках "Эксперт".
Ответ 4
Опция заключается в использовании формата doxygen для написания комментариев - это имеет дополнительное преимущество, заключающееся в возможности генерировать html/latex и другие виды документов для вашего кода.