Хотите улучшить этот вопрос? Обновите вопрос, чтобы ответить на него фактами и цитатами, отредактировав этот пост .
Закрыт в прошлом году .
У всех нас есть хорошая привычка документировать наш код, да?
В настоящее время в документации внутри кода есть синтаксис. почти как язык программирования на себя. Вопросы:
Какие (Сколько) синтаксис документации спецификации существуют?
Существует ли стандартный синтаксис документации?
Кто определяет этот стандарт? Существует ли официальный комитет или орган (например, для определения стандартов C ++)?
Или «doxygen» стал стандартом де-факто?
Трудно не слышать о doxygen. Это упоминается в каждом проекте программного обеспечения с открытым исходным кодом, в котором я принимал участие. Тем не менее, глядя на официальный сайт doxygen, далеко не очевидно, что doxygen определяет какую-либо спецификацию! Впечатление, которое я получаю, когда Я прочитал «как это может мне помочь», это то, что doxygen - это просто программа для извлечения документации в коде и представления ее на красивых HTML-страницах. Глядя на главную страницу doxygen, я мог даже подумать, что doxygen может использовать любой синтаксис документации , определенный в спецификациях сторонних производителей , извлечь его и вывести в виде HTML.
Кроме того, интересно отметить, что веб-сайт doxygen не использует заглавную букву слова doxygen, как если бы это был не бренд их программного обеспечения, а нарицательное (хорошо, не так ли?)
Что такое doxygen на самом деле?
механизм парсинга?
механизм рендеринга HTML?
библиотека, которая может использоваться сторонним программным обеспечением для рендеринга их собственных документов?
синтаксис документации (де-факто ) спецификация ?
все вышеперечисленное?
Меня особенно смущает связь между doxygen и другими синтаксическими анализаторами кода, такими как ANTLR , boost-spirit , Рагель ...
Например, что может делать doxygen, чего не может ANTLR, и что ANTLR может делать этого doxygen?
Также, глядя на проект Drupal. Они имеют:
свой собственный API-модуль , который является « реализацией подмножества спецификации генератора документации Doxygen ».
свой собственный модуль синтаксического анализатора (чтобы добавить к списку выше, вместе с самим doxygen, ANTLR и т. Д.).
их собственный веб-сайт API , на котором запущены два вышеупомянутых модуля, с документацией в коде «doxygen» в Drupal. ,
Итак, чтобы провести аналогию с C ++, кажется, что слово «doxygen» перегружено и означает разные вещи в разных контекстах.
В рамках проекта Drupal «doxygen» не относится к программному обеспечению, но просто (стандартная?) спецификация для синтаксиса документации, хотя, как я уже говорил выше, первая полоса самого сайта doxygen не претендует на то, чтобы быть такой!
Итак, мой прощальный вопрос:
Есть ли другая спецификация синтаксиса документации?