doxygen是（事实上）标准文档语法规范吗？ [英] Is doxygen the (de facto) standard documentation syntax specification?
问题描述
现在，代码内的文档本身有一个语法。它几乎像一个编程语言本身。问题是：
- 存在什么（多少）文档语法规范
- 是否有标准的文档语法？
- 谁定义了这个标准？是否有官方委员会或机构（像定义C ++标准一样）？
- 还是有doxygen成为事实上的标准？
听说过doxygen。在我参与的每个开源软件项目中都提到了，但是看官方的doxygen网站，很显然doxygen正在定义任何一种规范！我得到的印象当我阅读可以帮助我的方式时，doxygen只是一个提取代码内的文档并将其呈现在美丽的HTML页面中的软件。看看doxygen首页，我甚至可以认为doxygen可以使用第三方规范中定义的任何文档语法 ，并将其解压缩并以HTML格式输出。
此外，有趣的是，doxygen网站不会使用doxygen这个词，好像不是他们的品牌软件但是一个普通的名词（好吧，是吗？）
什么是doxygen真的？
- 解析引擎？
- HTML呈现引擎？
- 第三方软件可用于呈现自己的文档的库
- 一个文档语法（事实上）规范？
- 上述所有？
我对doxygen和其他代码解析器之间的关系感到特别困惑，如 ANTLR ， boost-spirit ， Ragel ...
例如doxygen可以做什么，ANTLR不能，ANTLR可以这样做t doxygen不能？
另外，看看Drupal项目。他们有：
- 他们自己的 API模块，它是Doxygen文档生成器规范子集的实现
- 他们自己的语法解析器模块（添加到上面的列表中，与doxygen本身一起，ANTLR等）。
- 他们自己的 API网站运行上述两个模块，介绍了Drupal代码中的doxygen文档。
所以，要采用C ++类比，似乎doxygen这个词是重载的，意味着不同的上下文中的不同的东西。
在Drupal项目中，doxygen不是指软件，而仅仅是文档语法的（标准？）规范，即使如上所述， doxygen网站的首页本身并不声称是这样的事情！
所以，我的分离问题是：
是否有任何其他文档语法规范？
存在什么（多少）文档语法规范？
几乎每个中等软件开发组织似乎都有自己的。通常它们被包含在编码风格指南的保护之下。
是否有标准的文档语法？
我有一些标准，我知道哪些有一些广泛的使用。这肯定不是一个全面的列表：
- JavaDoc
- C＃XML文档格式（ECMA-334）
- QDoc （有时被困惑为Doxygen）
- RubyDoc
- 普通老版文件（POD）
谁定义了这个标准？
没有标准。
是否有官方委员会或机构（像定义C ++标准一样）？
虽然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，Latex，RTF和UNIXman页面输出。
看看doxygen首页，我甚至可以认为doxygen可以使用第三方规范中定义的任何文档语法，并将其解压缩并输出它作为HTML。
不是任何，而是很多。
另外，有趣的是注意到doxygen网站不会使用doxygen这个词，就好像它不是他们的品牌软件，但是一个普通的名词（嗯，是吗？）
它不是商业产品，Dimitri不关心品牌。
什么是doxygen真的？
文档生成工具。
我对doxygen和其他代码解析器（如ANTLR，boost-spirit，Ragel ...）之间的关系感到特别困惑。 >
那些是解析库。
例如，doxygen可以做什么，ANTLR不能，而ANTLR可以doxygen不能？
像ANTLR这样的库用于构建软件，而Doxygen是用于生成文档的专用工具。所以当你可以使用ANTLR来编写一个文档生成器时，你不想使用Doxygen来构建一个编译器（我不会说不能，因为你可以肯定可以看到陌生的东西）。
有没有其他文档语法规范？
已经在上面回答。
希望这有帮助。
We all have the good habit of documenting our code, right?
Nowadays, in-code documentation itself has a syntax. It's almost like a programming language onto itself. The questions are:
- What (How many) documentation syntax specifications exist?
- Is there a standard documentation syntax?
- Who is defining this standard? Is there an official committee or body (like there is one for defining C++ standards)?
- Or has "doxygen" become the de-facto standard?
It's difficult not to have heard about doxygen. It is mentioned in every open source software project I have taken part in. Yet, looking at the official doxygen web site, it is far from obvious that doxygen is defining any kind of specification! The impression I get when I read "the ways it can help me", is that doxygen is simply a software to extract in-code documentation and present it in beautiful HTML pages. Looking at the doxygen front page, I could even think that doxygen could use any documentation syntax defined in 3rd party specifications and extract it and output it as HTML.
Also, it is interesting to note that the doxygen web site does not capitalize the word doxygen, as if it were not the brand of their software but a common noun (well, is it?)
What is doxygen really?
- a parsing engine?
- an HTML rendering engine?
- a library that can be used by 3rd party software to render their own docs?
- a documentation syntax (de facto) specification?
- all of the above?
I am particularly confused as to the relationship between doxygen and other code parsers like ANTLR, boost-spirit, Ragel...
For example, what is it that doxygen can do that ANTLR cannot, and that ANTLR can that doxygen cannot?
Also, looking at the Drupal project. They have:
- their own API module which is "an implementation of a subset of the Doxygen documentation generator specification".
- their own grammar parser module (to add to the list above, alongside doxygen itself, ANTLR, et all).
- their own API web site running the two aforementioned modules, presenting the Drupal in-code "doxygen" documentation.
So, to take a C++ analogy, it seems that the word "doxygen" is overloaded and means different things in different contexts.
Within the Drupal project, "doxygen" does not refer to a software, but simply a (standard?) specification for documentation syntax even though, as I said above, the front page of the doxygen web site itself does not claim to be such a thing!
So, my parting question is:
Is there any other documentation syntax specification?
What (How many) documentation syntax specifications exist?
Almost every medium software development organization seems to have their own. Often they are included under the umbrella of "coding style guidelines".
Is there a standard documentation syntax?
There are a few standards that I am aware of which have some widespread use. This is surely not a comprehensive list:
- JavaDoc
- The C# XML documentation format (ECMA-334)
- QDoc (sometimes confused as being the Doxygen)
- RubyDoc
- Plain Old Documentation (POD)
Who is defining this standard?
There is no standard.
Is there an official committee or body (like there is one for defining C++ standards)?
Not really, though the C# XML documentation format is managed by ECMA, which is a standards organization.
Or has "doxygen" become the de-facto standard?
Doxygen is not a standard. It reognizes a number of standards. See http://www.stack.nl/~dimitri/doxygen/features.html.
Typically most people use Doxygen to generate docs they wrote while loosely following either the QDoc standard or the JavaDoc standard. Often when people talk of "the" Doxygen standard, more often than not they mean the QDoc documentation style, plus some arbitrary usage of Doxygen extensions. My experience is that most organization using Doxygen aren't really following any particular convention very rigidly, simply because Doxygen doesn't enforce one.
...it is far from obvious that doxygen is defining any kind of specification!
It isn't.
doxygen is simply a software to extract in-code documentation and present it in beautiful HTML pages.
Yes exactly. It also supports XML, Latex, RTF, and UNIX "man" page outputs.
Looking at the doxygen front page, I could even think that doxygen could use any documentation syntax defined in 3rd party specifications and extract it and output it as HTML.
Not any, but many.
Also, it is interesting to note that the doxygen web site does not capitalize the word doxygen, as if it were not the brand of their software but a common noun (well, is it?)
Its not a commercial product, Dimitri doesn't care much about branding.
What is doxygen really?
A documentation generation tool.
I am particularly confused as to the relationship between doxygen and other code parsers like ANTLR, boost-spirit, Ragel...
Those are parsing libraries.
For example, what is it that doxygen can do that ANTLR cannot, and that ANTLR can that doxygen cannot?
Libraries like ANTLR are used to build software, while Doxygen is a specialized tool for generating documentation. So while you could use ANTLR to write a documentation generator, you wouldn't want to use Doxygen to build a compiler (I don't say can't, because surely you could, I have seen stranger things).
Is there any other documentation syntax specification?
Already answered above.
Hope this helps.
这篇关于doxygen是（事实上）标准文档语法规范吗？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
