Подтвердить что ты не робот

Является ли doxygen стандартной спецификацией синтаксиса документации (де-факто)?

У всех нас есть хорошая привычка документировать наш код, не так ли?

В настоящее время сама документация в коде имеет синтаксис. Это почти как язык программирования на себе. Вопросы:

  • Что (сколько) спецификаций синтаксиса документации существует?
  • Есть ли стандартный синтаксис документации?
  • Кто определяет этот стандарт? Есть ли официальный комитет или орган (например, есть один для определения стандартов на C++)?
  • Или "doxygen" стал стандартом де-факто?

Сложно не слышать о доксигене. Он упоминается в каждом проекте с открытым исходным кодом, в котором я принял участие. Однако, глядя на официальный веб-сайт doxygen, , далеко не очевидно, что doxygen определяет любую спецификацию!. когда я читаю "способы, которыми это может мне помочь", заключается в том, что doxygen - это просто программное обеспечение для извлечения документации в коде и представление его в красивых HTML-страницах. Глядя на страничку doxygen, я даже мог подумать, что doxygen может использовать любой синтаксис документации, определенный в сторонних спецификациях, и извлекать его и выводить как HTML.

Кроме того, интересно отметить, что веб-сайт doxygen не использует слова doxygen, как если бы это был не бренд их программного обеспечения, а общее существительное (ну, да?)

Что такое doxygen?

  • механизм синтаксического анализа?
  • движок рендеринга HTML?
  • библиотека, которая может использоваться сторонним программным обеспечением для рендеринга своих собственных документов.
  • спецификацию синтаксиса документации (де-факто)?
  • все вышеперечисленное?

Я особенно смущен относительно взаимосвязи между doxygen и другими анализаторами кода, например ANTLR, boost-spirit, Ragel...

Например, что может сделать doxygen, что ANTLR не может, и что ANTLR может это doxygen не может?

Также, глядя на проект Drupal. Они имеют:

  • их собственный API-модуль, который является "реализацией подмножества спецификации генератора документации Doxygen".
  • их собственный модуль анализа грамматики (чтобы добавить к списку выше, наряду с самим doxygen, ANTLR и т.д.).
  • их собственный веб-сайт API, содержащий два вышеупомянутых модуля, представляющих документацию Drupal in-code "doxygen" .

Итак, чтобы взять аналогию с С++, кажется, что слово "doxygen" перегружено и означает разные вещи в разных контекстах.

В проекте Drupal "doxygen" не относится к программному обеспечению, а просто (стандартная?) спецификация для синтаксиса документации, хотя, как я уже говорил выше, на первой странице самого веб-сайта doxygen не претендует на будь такой!

Итак, мой вопрос прощения:

Есть ли какая-либо другая спецификация синтаксиса документации?

4b9b3361

ОТВЕТЫ

Ответ 1

Сколько (сколько) спецификаций синтаксиса документации существует?

Похоже, что у каждой организации среднего развития программного обеспечения есть свои собственные. Часто они включаются под эгидой "правил стиля кодирования".

Есть ли стандартный синтаксис документации?

Есть несколько стандартов, о которых я знаю, которые широко используются. Это, безусловно, не полный список:

Кто определяет этот стандарт?

Нет стандарта.

Есть ли официальный комитет или орган (например, есть один для определения стандартов на C++)?

Не совсем, хотя формат документации С# XML управляется ECMA, который является организацией стандартов.

Или "доксиген" стал стандартом де-факто?

Doxygen не является стандартом. Он распознает ряд стандартов. См. http://www.stack.nl/~dimitri/doxygen/features.html.

Как правило, большинство пользователей используют Doxygen для генерации документов, которые они пишут, в то время как они свободно следуют либо стандарту QDoc, либо стандарту JavaDoc. Часто, когда люди говорят о "стандарте Doxygen", чаще всего они означают стиль документации QDoc, а также некоторое произвольное использование расширений Doxygen. Мой опыт в том, что большинство организаций, использующих Doxygen, не очень строго придерживаются какого-либо конкретного соглашения, просто потому, что Doxygen не применяет его.

... далеко не очевидно, что doxygen определяет любую спецификацию!

Это не так.

doxygen - это просто программное обеспечение для извлечения документации в коде и представление его в красивых HTML-страницах.

Да точно. Он также поддерживает выходы страницы "XML", "Латекс", "RTF" и "Человек".

Глядя на начальную страницу doxygen, я даже мог подумать, что doxygen может использовать любой синтаксис документации, определенный в сторонних спецификациях, и извлекать его и выводить как HTML.

Не все, но многие.

Кроме того, интересно отметить, что веб-сайт doxygen не использует слова doxygen, как если бы это был не бренд их программного обеспечения, а общее существительное (ну, да?)

Это не коммерческий продукт, Димитрий не очень заботится о брендинге.

Что такое doxygen?

Инструмент создания документации.

Я особенно смущен относительно взаимосвязи между doxygen и другими анализаторами кода, такими как ANTLR, boost-spirit, Ragel...

Это синтаксический анализ библиотек.

Например, что может сделать doxygen, что ANTLR не может, и что ANTLR может это doxygen не может?

Библиотеки, такие как ANTLR, используются для создания программного обеспечения, а Doxygen - это специализированный инструмент для создания документации. Поэтому, хотя вы можете использовать ANTLR для написания генератора документации, вы не захотите использовать Doxygen для сборки компилятора (я не говорю, не могу, потому что, конечно, вы могли бы, я видел более странные вещи).

Есть ли какая-либо другая спецификация синтаксиса документации?

Уже ответил выше.

Надеюсь, что это поможет.

Ответ 3

Вы правы - Doxygen - это скорее приложение для извлечения документации, чем "стандарт комментариев" как таковой. Он поддерживает множество различных стилей документации - JavaDoc (с '@', представляющим команду), вариант Doxygen (с '\', вводящим те же команды), Documentation XML и многие варианты в формате блока комментариев, который разрешен. Он также может использовать форматирование комментариев для указания того, какой контент (например, краткие описания не должны помечены как таковые и могут быть взяты из первого предложения или абзаца текста и т.д.)

Таким образом, он очень настраивается, но позволяет почти каждому программисту иметь свой собственный стиль, который приводит к нестандартному беспорядку от одного проекта к другому и часто между разными комментариями в рамках одного проекта - даже когда они написаны одним программист! Положительная сторона заключается в том, что до тех пор, пока комментарий остается в базовом стиле, Doxygen будет правильно извлекать документы для вас и форматировать их в согласованный внешний документ. Минус-сторона заключается в том, что, хотя многие программисты "используют комментарии doxygen" (что звучит стандартизованно), их форматы комментариев часто могут быть совершенно разными.

Одно из решений (для Visual Studio), которое может по крайней мере помочь с этим несоответствием стилей в вашем собственном проекте/команде/компании, - это добавление, которое я написал, AtomineerUtils. Это поможет вам авторизовать и обновить комментарии формата документа Doxygen, JavaDoc и XML - он автоматически генерирует документацию, чтобы сэкономить много времени, и обновляет комментарии, чтобы синхронизировать их с изменениями кода. Во время этого процесса он может переформатировать комментарий для достижения очень последовательного и читаемого стиля (заказывать записи в стандартном формате, накладывать пустые строки между комментариями и кодом и между записями, переносить текст в записи и т.д.). Пользователь может настроить шаблоны, которые точно контролируют, как все это работает, поэтому легко достичь именно того стиля, который вы хотите, но сделать его согласованным во всех ваших проектах. Это улучшает согласованность, когда у вас более одного программиста, работающего над текстом кода.

Если вы документируете в Visual Studio, я бы рекомендовал формат документации XML. Это не так понятно для человека, как стили Doxygen/JavaDoc, но он используется средой IDE для предоставления живого intellisense данных по коду при вводе и экспортируется в файлы XML, которые любое приложение может легко обрабатывать, что дает вам гораздо больше гибкость. Doxygen может создавать документы из этого формата, поэтому вы также можете использовать инструменты Doxygen с комментариями источника XML.

Ответ 4

Есть ли другая спецификация синтаксиса документации?

Да, конечно. Например, там JavaDoc (или, тем не менее, это написано). И материал Microsoft XML (но это называется).

Однако, похоже, doxygen в значительной степени является де-факто стандартом на арене Open Source С++. Когда я впервые услышал о doxygen (~ 10 лет назад), вокруг были другие, но, похоже, они исчезли.