Is doxygen the (de facto) standard documentation syntax specification? [closed]

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 4 years ago.

Improve this question

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开发者_JS百科 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 recognizes a number of standards. See http://www.doxygen.nl/manual/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.

---

there is no standard.

Doxygen style is almost standard (gcc template library uses it).

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

---

You are right - Doxygen is more of a documentation extraction application than a "commenting standard" per se. It supports many different documentation styles - JavaDoc (with '@' introducing a command), a Doxygen variant (with '\' introducing the same commands), Documentation XML, and many variations on the comment block format that is allowed. It is also able to use the formatting of comments to indicate what content is (e.g. brief descriptions need not be tagged as such, and can be taken from the first sentence or paragraph of the text, etc.)

As such, it is highly configurable but allows almost every programmer to have their own style which leads to a nonstandard mess from one project to another, and often between different comments within a single project - even when they are written by a single programmer! The plus side is that as long as the comment stays within the basic style, Doxygen will correctly extract the docs for you and format them all into a consistent external document. The minus side is that although many programmers "use doxygen comments" (which sounds standardised), their comment formats can often be totally dissimilar.

One solution (for Visual Studio) that can at least help with this disparity of styles within your own project/team/company is an addin I've written, AtomineerUtils. This helps you to author and update Doxygen, JavaDoc and XML documentation format comments - it auto-generates documentation to save lots of time, and updates comments to keep them in sync with changes to the code. During this process it can reformat the comment to achieve a very consistent and readable style (order the entries in a standard format, enforce blank lines between comments and code and between entries, word-wrap the text in entries, etc). The user can set up templates that control exactly how all of this works, so it's easy to achieve precisely the style you want, but make it consistent across all your projects. This improves consistency a lot when you have more than one programmer working on a body of code.

If you are documenting in Visual Studio, I would recommend the XML documentation format. It's not as human-readable as Doxygen/JavaDoc styles can be, but it's used by the IDE to provide live intellisense data on code as you type, and is exported to XML files that any application can easily process, which gives you a lot more flexibility. Doxygen can build docs from this format, so you can stil use the Doxygen tools with XML source comments too.

---

Is there any other documentation syntax specification?

Yes, of course. For example, there's JavaDoc (or however that's spelled). And Microsoft's XML stuff (however that's called).

However, it seems doxygen is pretty much the de-facto standard in the Open Source C++ arena, though. When I originally heard about doxygen (~10 years ago), there used to be others around, but it seems they've vanished.