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

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

Answer 1

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.