Martin Sebor wrote:
>
>Eric Lemings wrote:
>>
>> Travis Vitek wrote:
>>>
>>> Martin Sebor wrote:
>>>>
>>>> I thought we said we wouldn't be using doxygen comments in
>>>> library code. Am I misremembering?
>>>>
>>> I know that it was requested that I remove the doxygen
>>> comments from the
>>> type traits stuff I have been working on, but I decided it
>>> would be best
>>> to commit them with the comments intact and remove them only if
>>> necessary. I mentioned this to Brad in our off-list
>>> correspondence, and
>>> he has opted to do the same.
>>>
>>> As I sit here thinking about it, I can't remember exactly why it was
>>> decided that they should be removed. Perhaps it is best to have this
>>> discussion again, but on the list this time.
>>>
>>> To start, I'm not sure I understand the motivation for _not_ using
>>> doxygen in the library headers. I realize that having documentation
>>> in the code is a departure from what stdcxx has done in the past,
>>> but I'm not convinced that this is a bad thing.
>>
>> I'll add a couple points to that for the record.
>>
>> Much of this was precipitated when I noticed that GNU libstdc++ also
>> includes their documentation right in the library headers and source
>> code. Why? Because most, if not all, C/C++ preprocessors will strip
>> comments by default during a first pass. Thus, the impact of
>> extensive documentation comments on overall build times is
>> negligible.
>
>Of course preprocessors strip comments. It's required by
>the language standards. But regardless of the translation
>stage at which the stripping takes place, it isn't without
>cost.
>
>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
> product
Since 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
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 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.
>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 code
If 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.
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.
>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
> purpose
Which 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.
>
>4) the HTML generated from stdcxx headers is unavoidably
> ugly because of the necessity to uglify names (leading
> underscores, etc.)
I thought leading underscores made code run faster. :)
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.
>
>Martin
>
