You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@stdcxx.apache.org by Martin Sebor <se...@roguewave.com> on 2008/06/23 17:17:55 UTC
Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Eric Lemings wrote:
>
> Gah. I have to update my docs as well: template parameters are
> documented using the @tparam tag rather than the @param tag.
I thought we said we wouldn't be using doxygen comments in
library code. Am I misremembering?
Martin
>
> http://www.stack.nl/~dimitri/doxygen/commands.html#cmdtparam
>
> Brad.
>
>> -----Original Message-----
>> From: Travis Vitek
>> Sent: Monday, June 16, 2008 11:47 AM
>> To: Eric Lemings
>> Subject: RE: svn commit: r667636 -
>> /stdcxx/branches/4.3.x/include/rw/_forward.h
>>
>>
>> Damn, now I have to update my dox.
>>
>>> -----Original Message-----
>>> From: Eric Lemings
>>> Sent: Monday, June 16, 2008 10:44 AM
>>> To: Travis Vitek
>>> Subject: RE: svn commit: r667636 -
>>> /stdcxx/branches/4.3.x/include/rw/_forward.h
>>>
>>>
>>>
>>>> -----Original Message-----
>>>> From: Travis Vitek
>>>> Sent: Monday, June 16, 2008 10:21 AM
>>>> To: Eric Lemings
>>>> Subject: RE: svn commit: r667636 -
>>>> /stdcxx/branches/4.3.x/include/rw/_forward.h
>>>>
>>>>
>>>>
>>>>
>>>>> Author: elemings
>>>>> Date: Fri Jun 13 13:16:06 2008
>>>>> New Revision: 667636
>>>>>
>>>>> +/**
>>>>> + * An identity wrapper. Similar to the identity property,
>>>>> the identity
>>>>> + * wrapper is a class template that simply reflects the
>> type of its
>>>>> + * template parameter. This class template is used when
>> a template
>>>>> + * parameter type must be explicitly specified in order to
>>> apply the
>>>>> + * correct move/forwarding semantics, usually in the \c
>>>> std::forward()
>>>>> + * function.
>>>>> + *
>>>>> + * @param _Type Any type. No restrictions or requirements.
>>>>> + * @see std::forward
>>>>> + */
>>>>> +template <class _Type>
>>>>> +struct identity
>>>> Does doxygen handle @param when we are talking about a
>>>> template parameter?
>>> Not yet.
>>>
>>> http://www.mail-archive.com/debian-bugs-closed@lists.debian.org
>>> /msg163022.html
>>>
RE: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Posted by Eric Lemings <Er...@roguewave.com>.
> -----Original Message-----
> From: Martin Sebor [mailto:sebor@roguewave.com]
> Sent: Tuesday, June 24, 2008 9:00 AM
> To: dev@stdcxx.apache.org
> Subject: Re: svn commit: r667636 -
> /stdcxx/branches/4.3.x/include/rw/_forward.h
>
> Eric Lemings wrote:
> >
> >
> >> -----Original Message-----
> >> From: Martin Sebor [mailto:sebor@roguewave.com]
> >> Sent: Tuesday, June 24, 2008 6:55 AM
> >> To: dev@stdcxx.apache.org
> >> Subject: Re: svn commit: r667636 -
> >> /stdcxx/branches/4.3.x/include/rw/_forward.h
> >>
> >> Eric Lemings wrote:
> > ...
> >>> BTW, I'm still trying to figure out what it is that you are
> >> proposing
> >>> exactly. :D
> >> We have an established (albeit undocumented) process and
> >> infrastructure for documenting code and publishing the
> >> documentation. The onus is on you and Travis to come up
> >> with a proposal if you want to change how things are done.
> >
> > I thought I did. To repeat...for the record, write new
> documentation
> > using Doxygen comments now. Migrate the old HTML docs later.
>
> Sorry. One sentence doesn't make a proposal, certainly not
> one this vague.
I can write a 1000 word, detailed proposal in about an hour if
that would do any good. In the meantime, most of the details
are in the Jira issue.
http://issues.apache.org/jira/browse/STDCXX-964
>
...
> The current process is to maintain the existing docs in HTML,
> using the existing infrastructure to publish the docs on the
> site. You want to change it? Fine. Propose in detail how and
> when this will change will take place and when we can expect
> it to be done.
Okay.
Brad.
Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Posted by Martin Sebor <se...@roguewave.com>.
Eric Lemings wrote:
>
>
>> -----Original Message-----
>> From: Martin Sebor [mailto:sebor@roguewave.com]
>> Sent: Tuesday, June 24, 2008 6:55 AM
>> To: dev@stdcxx.apache.org
>> Subject: Re: svn commit: r667636 -
>> /stdcxx/branches/4.3.x/include/rw/_forward.h
>>
>> Eric Lemings wrote:
> ...
>>> BTW, I'm still trying to figure out what it is that you are
>> proposing
>>> exactly. :D
>> We have an established (albeit undocumented) process and
>> infrastructure for documenting code and publishing the
>> documentation. The onus is on you and Travis to come up
>> with a proposal if you want to change how things are done.
>
> I thought I did. To repeat...for the record, write new documentation
> using Doxygen comments now. Migrate the old HTML docs later.
Sorry. One sentence doesn't make a proposal, certainly not
one this vague.
>
>> So far you've decided on your own, despite my objections
>> and without establishing consensus, to start adding Doxygen
>> style comments to new headers, without reconciling the
>> differences between the existing process and your new one,
>> and without providing a clear path to such a reconciliation
>> in the foreseeable future.
>
> Hmm. Let me see if I can summarize your objections:
>
> 1. You don't like Doxygen.
>
> I think that's pretty evident. :)
Not at all. You completely misinterpreted what I said.
> Nothing wrong with that. I think
> it's the best damn doc tool on the market...but that's just me. But if
> you know of a better tool and/or format, we're all ears.
>
> 2. We shouldn't write any documentation comments because it's not
> conventional.
Nope. Again, you're missing my point. I'm saying changes
to process should be made only with a solid plan in place
and with consensus.
>
> Convention isn't really the right: this is becoming more like dogma.
>
> Travis and I both realize what this means -- breaking with this
> convention -- moving forward. It's not easy writing docs and code at
> the same time, and the new code will look different from the older code
> (for a period of time at least), but it is the right thing to do we
> believe.
I disagree.
>
>> Unless these issues are satisfactorily resolved and until
>> there is a viable plan for producing a adequate replacement
>> for the existing class reference on a reasonable schedule
>> I have to insist that the Doxygen comments be removed from
>> the newly added headers.
>
> And then what? Hope that the documentation magically appears? I'd be
> glad to remove it...if you have a better plan, solution, proposal...
> something in mind.
The current process is to maintain the existing docs in HTML,
using the existing infrastructure to publish the docs on the
site. You want to change it? Fine. Propose in detail how and
when this will change will take place and when we can expect
it to be done.
>
> But just removing the documentation comments is not "a clear path to
> such reconciliation in the foreseeable future" either. It's the
> absolute last thing we should be contemplating in fact.
RE: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Posted by Eric Lemings <Er...@roguewave.com>.
> -----Original Message-----
> From: Martin Sebor [mailto:sebor@roguewave.com]
> Sent: Tuesday, June 24, 2008 6:55 AM
> To: dev@stdcxx.apache.org
> Subject: Re: svn commit: r667636 -
> /stdcxx/branches/4.3.x/include/rw/_forward.h
>
> Eric Lemings wrote:
...
> > BTW, I'm still trying to figure out what it is that you are
> proposing
> > exactly. :D
>
> We have an established (albeit undocumented) process and
> infrastructure for documenting code and publishing the
> documentation. The onus is on you and Travis to come up
> with a proposal if you want to change how things are done.
I thought I did. To repeat...for the record, write new documentation
using Doxygen comments now. Migrate the old HTML docs later.
>
> So far you've decided on your own, despite my objections
> and without establishing consensus, to start adding Doxygen
> style comments to new headers, without reconciling the
> differences between the existing process and your new one,
> and without providing a clear path to such a reconciliation
> in the foreseeable future.
Hmm. Let me see if I can summarize your objections:
1. You don't like Doxygen.
I think that's pretty evident. :) Nothing wrong with that. I think
it's the best damn doc tool on the market...but that's just me. But if
you know of a better tool and/or format, we're all ears.
2. We shouldn't write any documentation comments because it's not
conventional.
Convention isn't really the right: this is becoming more like dogma.
Travis and I both realize what this means -- breaking with this
convention -- moving forward. It's not easy writing docs and code at
the same time, and the new code will look different from the older code
(for a period of time at least), but it is the right thing to do we
believe.
>
> Unless these issues are satisfactorily resolved and until
> there is a viable plan for producing a adequate replacement
> for the existing class reference on a reasonable schedule
> I have to insist that the Doxygen comments be removed from
> the newly added headers.
And then what? Hope that the documentation magically appears? I'd be
glad to remove it...if you have a better plan, solution, proposal...
something in mind.
But just removing the documentation comments is not "a clear path to
such reconciliation in the foreseeable future" either. It's the
absolute last thing we should be contemplating in fact.
Brad.
Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Posted by Martin Sebor <se...@roguewave.com>.
Eric Lemings wrote:
>
> On Jun 23, 2008, at 9:31 PM, Martin Sebor wrote:
>
>> 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
>>>> 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
>>
>> 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?
>
> I don't think any of those choice are viable _in the near term_ but if I
> had to choose?
>
> C. If only to get a better idea of how much work we're really talking
> about.
[...]
> BTW, I'm still trying to figure out what it is that you are proposing
> exactly. :D
We have an established (albeit undocumented) process and
infrastructure for documenting code and publishing the
documentation. The onus is on you and Travis to come up
with a proposal if you want to change how things are done.
So far you've decided on your own, despite my objections
and without establishing consensus, to start adding Doxygen
style comments to new headers, without reconciling the
differences between the existing process and your new one,
and without providing a clear path to such a reconciliation
in the foreseeable future.
Unless these issues are satisfactorily resolved and until
there is a viable plan for producing a adequate replacement
for the existing class reference on a reasonable schedule
I have to insist that the Doxygen comments be removed from
the newly added headers.
Martin
Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Posted by Eric Lemings <er...@roguewave.com>.
On Jun 23, 2008, at 9:31 PM, Martin Sebor wrote:
> 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
>>> 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
>
> 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?
I don't think any of those choice are viable _in the near term_ but if
I had to choose?
C. If only to get a better idea of how much work we're really talking
about.
But I don't think doing that right now is really necessary. I think
we all agree, there's too much C++0x work to be done in the near term
that virtually prohibits migrating the old HTML docs right now. But
that doesn't mean we should not be writing new documentation.
> ...
>> 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.
I agree... to a degree. We don't have the bandwidth at present but it
is not at all clear (to me at least) how much work this migration will
really require.
> ...
> 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.
I don't think there's anything that prevents us from copying and
redistributing our own documentation. You only need Doxygen installed
if you need to regenerate the docs for some reason.
> And because the docs aren't being
> generated and the generated HTML looked they're likely to contain
> all kinds of formatting problems.
I've generated them. And yes, there are formatting problems.
> ...
>> 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.
A better tool/format than Doxygen? Wow. I'd be interested in reading
that thread of discussion! Link?
BTW, I'm still trying to figure out what it is that you are proposing
exactly. :D
Brad.
Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Posted by Martin Sebor <se...@roguewave.com>.
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
>> 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
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 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.
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
>> 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.
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
>>
RE: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Posted by Travis Vitek <Tr...@roguewave.com>.
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
>
RE: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Posted by Eric Lemings <Er...@roguewave.com>.
> -----Original Message-----
> From: Martin Sebor [mailto:sebor@roguewave.com]
> Sent: Monday, June 23, 2008 11:38 AM
> To: dev@stdcxx.apache.org
> Subject: Re: svn commit: r667636 -
> /stdcxx/branches/4.3.x/include/rw/_forward.h
>
> Eric Lemings wrote:
> >
> >
> >> -----Original Message-----
> >> From: Travis Vitek [mailto:Travis.Vitek@roguewave.com]
> >> Sent: Monday, June 23, 2008 10:13 AM
> >> To: dev@stdcxx.apache.org
> >> Subject: RE: svn commit: r667636 -
> >> /stdcxx/branches/4.3.x/include/rw/_forward.h
> >>
> >>
> >>
> >> Martin Sebor wrote:
> >>> Eric Lemings wrote:
> >>>>
> >>>> Gah. I have to update my docs as well: template parameters are
> >>>> documented using the @tparam tag rather than the @param tag.
> >>> 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
What Travis said: if we don't write it ourselves, it probably won't
get written. :) I also agree: I'd rather write doc comments than
update the existing raw HTML docs.
>
> 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
That's subjective. Because they are more structured than free-form
comments, I find them easier to read.
>
> 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
I consider that icing on the cake. You can still generate docs
without having them published online.
>
> 4) the HTML generated from stdcxx headers is unavoidably
> ugly because of the necessity to uglify names (leading
> underscores, etc.)
This can be controlled with conditional sections and comments, using
@if tags, @internal tags, _RWSTD_EXT_DOXYGEN macro, and other such
mechanisms.
Brad.
Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Posted by Martin Sebor <se...@roguewave.com>.
Eric Lemings wrote:
>
>
>> -----Original Message-----
>> From: Travis Vitek [mailto:Travis.Vitek@roguewave.com]
>> Sent: Monday, June 23, 2008 10:13 AM
>> To: dev@stdcxx.apache.org
>> Subject: RE: svn commit: r667636 -
>> /stdcxx/branches/4.3.x/include/rw/_forward.h
>>
>>
>>
>> Martin Sebor wrote:
>>> Eric Lemings wrote:
>>>>
>>>> Gah. I have to update my docs as well: template parameters are
>>>> documented using the @tparam tag rather than the @param tag.
>>> 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
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
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
4) the HTML generated from stdcxx headers is unavoidably
ugly because of the necessity to uglify names (leading
underscores, etc.)
Martin
RE: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Posted by Eric Lemings <Er...@roguewave.com>.
> -----Original Message-----
> From: Travis Vitek [mailto:Travis.Vitek@roguewave.com]
> Sent: Monday, June 23, 2008 10:13 AM
> To: dev@stdcxx.apache.org
> Subject: RE: svn commit: r667636 -
> /stdcxx/branches/4.3.x/include/rw/_forward.h
>
>
>
> Martin Sebor wrote:
> >
> >Eric Lemings wrote:
> >>
> >> Gah. I have to update my docs as well: template parameters are
> >> documented using the @tparam tag rather than the @param tag.
> >
> >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.
I believe Travis did some quick performance tests to verify these
empirical conclusions.
Brad.
RE: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Posted by Travis Vitek <Tr...@roguewave.com>.
Martin Sebor wrote:
>
>Eric Lemings wrote:
>>
>> Gah. I have to update my docs as well: template parameters are
>> documented using the @tparam tag rather than the @param tag.
>
>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.
Travis
>Martin
>
>>
>> http://www.stack.nl/~dimitri/doxygen/commands.html#cmdtparam
>>
>> Brad.