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?