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

Question

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

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

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

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

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

Что такое доксиген?

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

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

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

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

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

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

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

Итак, мой прощальный вопрос:

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

Answer 1

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

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

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

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

• JavaDoc
• C# XML формат документации (ECMA-334)
• QDoc (иногда путают как на Doxygen)
• RubyDoc
• Plain Old Documentation (POD)

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

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

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

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

Или у вас есть «doxygen», который стал стандартом де-факто?

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, форсирует-дух, Ragel ...

Того разбор библиотеки.

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

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

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

Уже ответил (а) выше.

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

Answer 2

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

Doxygen стиль почти стандартный (библиотека шаблонов gcc использует его).

http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

Answer 3

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

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

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

Answer 4

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

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

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

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