Travis Vitek wrote:
Martin Sebor wrote:
[...]
I gave a number of arguments against Doxygen comments in stdcxx headers:1) existing code doesn't use it and converting the raw HTML docs to Doxygen is an enormous task that none of us has the time to take on; Doxygenating new code without doing the same for the existing code is inconsistent and won't help us produce end-user documentation for the finished productSince we aren't providing any html documentation for any c++0x code at this time, maybe we should stop using html documentation? :P So the options are-- a) not document the c++0x code at all b) write up documentation for all new code in html to be consistent with what is used currently c) move all existing documentation over to doxygen before a single doxygen comment is added to the new code
Assuming we want to have C++ 0x fully documented in 5.0 or shortly thereafter which of (b) and (c) do you think is viable?
Another important point is that the stdcxx project doesn't have anyone volunteering time to write documentation. If we want the documentation, we're likely going to have to do it ourselves, and I find using doxygen comments _much_ simpler than writing html.
I agree. But that won't help us migrate the reams of existing docs to Doxygen. Without the migration I see no point in documenting new code in one format and old code in another. A substantial amount of C++ 0x code will also involve changing the old code (such as adding new member functions to containers or adding requirements clauses). We can't very well document these changes in Doxygen and leave the existing HTML docs unchanged.
I know that at Rogue Wave we have an xslt that transforms from doxygen generated xml files to html documentation, so unless using doxygen is totally ruled out, that can be used to bridge between the old html pages and generated ones.
Yes, but the transformation isn't fully automated and according to Marc requires quite a bit of human intervention. It's clear that we don't have the bandwidth to take this on and still make our target date.
2) Doxygen markups are harder to read than ordinary comments (see 3), and in the library headers the volume of such comments will, in many cases, dwarf the amount of codeIf the code is well written, comments are usually reserved for situations where they are necessary to describe what the code is actually supposed to be doing. Most frequently this type of comment would be found in the body of a function definition. Doxygen comments, on the other hand, usually appear with the declarations, so the type of comments that you would usually need to read aren't necessarily in the same place as the doxygen comments. Additionally, your editor can likely be configured to hide the doxygen comments if you don't want to see them.
I've seen Doxygen comments. A simple example of the differences is the recently added Doxygenized documentation of the rw_prinf() format specifiers vs what we had before. I find the original raw text comments much more readable than the only moderately heavily marked up replacement.
As for readability, consider this. There are currently no comments describing what a given library class or function is expected to do. If you want to see what the expected behavior is, you get to walk yourself through the implementation, or you get to fire up a web browser and look at the html documentation. If the documentation is added as doxygen comments, they are in the code. They may be slightly less readable than plain english text due to the additional markup, but there is _nothing_ that is stopping you from looking to the implementation or firing up a web browser like you did before.
For starters, what prevents me from browsing all new Doxygen docs is that there is no generated HTML documentation. I and everyone else would have to install Doxygen and compile the HTML docs ourselves to get the benefit. And because the docs aren't being generated and the generated HTML looked they're likely to contain all kinds of formatting problems.
3) unless/until there is infrastructure to generate the HTML docs from the Doxygen comments documenting the library (or other parts of stdcxx) using Doxygen markups serves no purposeWhich would you like first, the chick or the egg? The infrastructure will never be built to generate html documentation from doxygen comments if we don't have doxygen comments to generate documentation from.
FYI: We've had Doxygen comments in place for parts of the test driver (including the whole exec utility) in place for two years now. No one has had the time or the energy to set things up. I don't see anyone stepping up and tackling any of the open documentation issues, including STDCXX-964. But to answer your question, I believe the infrastructure to generate the docs must be in place first, just like build infrastructure needs to exist before any non-trivial amount of code can be written. AFAIK, Doxygen can be run on straight source code with no markups.
4) the HTML generated from stdcxx headers is unavoidably ugly because of the necessity to uglify names (leading underscores, etc.)
[...]
Doxygen doesn't have to document everything that it sees. There are many ways to control what will be documented. You can tell it to only generate documentation for things that have doxygen style comments or you can mark things as internal so the documentation can be conditionally disabled.
I've seen the libstdc++ documentation (see below) and talked to the project's maintainers. My understanding is that they're not completely happy with it for some of the same reasons I've raised here and are considering (or maybe even working on) migrating away from Doxygen to some other tool/format. http://gcc.gnu.org/onlinedocs/libstdc++/api.html
Martin
