doxygen是（事实上）标准文档语法规范吗？ [英] Is doxygen the (de facto) standard documentation syntax specification?

问题描述

我们都有记录我们的代码的好习惯，对吗？

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:

• 有多少文档语法？


• 是否有标准文档语法？


• 谁在定义此标准？是否有一个官方委员会或机构（如有一个定义C ++标准）？


• 或者有doxygen成为事实上的标准？

• 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?

听说过doxygen。在我参与的每个开源软件项目中都提到。但是，看着官方的doxygen网站， doxygen定义任何类型的规范远远不是很明显！我得到的印象当我阅读它的方式可以帮助我，是doxygen只是一个软件提取代码中的文档，并在美丽的HTML页面。看看doxygen的首页，我甚至可以认为doxygen可以使用第三方规范中定义的任何文档语法 并提取它并将其输出为HTML。

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.

此外，有趣的是，doxygen网站不会将大小写字词doxygen大写，因为它不是他们的品牌

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?)

什么是doxygen？

What is doxygen really?

• 一个解析引擎


• 是一个HTML渲染引擎？


• 一个库，可供第三方软件使用，




• 所有上述文件？

• 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?

我对doxygen和其他代码解析器之间的关系特别困惑，例如 ANTLR ，精神提升， Ragel ...

I am particularly confused as to the relationship between doxygen and other code parsers like ANTLR, boost-spirit, Ragel...

例如，doxygen可以做什么，ANTLR无法做到，ANTLR可以doxygen不能？

For example, what is it that doxygen can do that ANTLR cannot, and that ANTLR can that doxygen cannot?

此外，看看Drupal项目。他们拥有：

Also, looking at the Drupal project. They have:

• 自己的 API模块 project / grammar_parser>语法解析器模块（添加到上面的列表中，与doxygen本身，ANTLR等等）。


• 自己的API网站运行上述两个模块，展示Drupal的代码doxygen文档。

• 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.

因此，为了进行C ++比喻，似乎词doxygen是重载的，意味着不同的上下文中的不同的东西。

So, to take a C++ analogy, it seems that the word "doxygen" is overloaded and means different things in different contexts.

在Drupal项目中，doxygen不是指一个软件，而是一个用于文档语法的标准规范，即使如上所述，前端的doxygen网站本身并不声称是这样的东西！

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


• C＃XML文档格式（ECMA-334）


• QDoc （有时会被混淆为Doxygen）


• RubyDoc


• 普通旧文档（POD）

• 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?

没有标准。

是否有正式的委员会或机构（例如有定义C ++标准的委员会或机构）？

Is there an official committee or body (like there is one for defining C++ standards)?

不是真的，虽然C＃XML文档格式由ECMA管理，它是一个标准组织。

Not really, though the C# XML documentation format is managed by ECMA, which is a standards organization.

还是有doxygen成为事实上的标准？

Or has "doxygen" become the de-facto standard?

Doxygen不是标准。它认识到一些标准。请参见 http://www.stack.nl/~dimitri/doxygen/features.html 。

Doxygen is not a standard. It reognizes a number of standards. See http://www.stack.nl/~dimitri/doxygen/features.html.

通常，大多数人使用Doxygen生成他们在遵循QDoc标准或JavaDoc标准的情况下写入的文档。通常当人们谈论theDoxygen标准时，往往不是他们意味着QDoc文档风格，加上一些任意使用Doxygen扩展。我的经验是，大多数组织使用Doxygen并不真的遵循任何特定的惯例非常僵硬，只是因为Doxygen不强制执行。

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.

... doxygen定义任何类型的规范并不明显。

...it is far from obvious that doxygen is defining any kind of specification!

不是。

doxygen只是一个软件提取代码中的文档，并在美丽的HTML页面。

doxygen is simply a software to extract in-code documentation and present it in beautiful HTML pages.

是的。它还支持XML，Latex，RTF和UNIXman页面输出。

Yes exactly. It also supports XML, Latex, RTF, and UNIX "man" page outputs.

查看doxygen的首页，我甚至可以认为doxygen可以使用第三方规范中定义的任何文档语法，并提取和输出它作为HTML。

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.

不是任何，但很多。

此外，有趣的是，doxygen网站没有使doxygen这个词大写，好像它不是他们的品牌软件，但是一个普通的名词（嗯，是吗？）

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?)

Dimitri不是一个商业产品，

Its not a commercial product, Dimitri doesn't care much about branding.

什么是doxygen？

What is doxygen really?

文档生成工具。

我对doxygen和其他代码解析器如ANTLR，boost-spirit，Ragel ...之间的关系感到特别困惑。 >

I am particularly confused as to the relationship between doxygen and other code parsers like ANTLR, boost-spirit, Ragel...

这些是解析库。

例如，doxygen可以做什么，ANTLR不能，而ANTLR可以doxygen不能？

For example, what is it that doxygen can do that ANTLR cannot, and that ANTLR can that doxygen cannot?

像ANTLR这样的库用于构建软件，而Doxygen是用于生成文档的专用工具。所以，虽然你可以使用ANTLR写一个文档生成器，你不会希望使用Doxygen来构建一个编译器（我不说不能，因为肯定你可以，我看到陌生的东西）。

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?

以上已回答。

希望这有助。

这篇关于doxygen是（事实上）标准文档语法规范吗？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！