Doxygen - another sample, preliminary comments
Rich Churcher
churcher@ihug.com.au
Wed Nov 22 15:49:00 GMT 2000
Benjamin Kosnik <bkoz@redhat.com> writes:
> All this Doxygen stuff looks extremely promising. I'd like to start
> checking in patches to make the libstdc++ documentation use it.
>
> >From where I'm sitting, this is what I'd like to see:
>
> 1) minimal changes to the source files
> (I will, however, accept changes to the source files to get these
> docs. The changes appear to be quite minimal)
Briefly - what level of commenting in the source files is acceptable?
For example, should each standard function have a one-liner containing
a brief description and maybe even a standard reference:
/// Inform a vector of a planned change in size. 23.2.4.2
void reserve(size_type __n) {
// ... snip ...
}
Or is even this much going to clutter the source unacceptably? I
wouldn't want to put whole tracts of documentation into the code,
obviously, but it might be beneficial to have simple comments for each
major feature.
I can just see hordes of developers throwing up their hands in horror
;o)
One of the concerns I have with this approach is - what happens when
SGI releases another version of the header? We'd basically have to
reinsert the documentation by hand, which sounds far too much like
hard work. This isn't such a problem for the non-SGI headers, of
course.
For this reason, I'm tending towards leaving the current source
untouched and doing everything from a separate directory. Maybe we
could use a configure switch to prevent the docs being generated, if
desired. This would allow for those who dislike the Doxygen approach,
and those die-hards who always do everything from the source code <g>
> 2) some kind of script for getting consistent, up-to-date output with
> the minimum of manual tweaking. The more we can automate this with
> scripts, the better. After we get a script that's working, we can
> just add a Makefile rule, similar to the old TAGS rule.
Beyond me, I'm afraid. I'm sure some bright cookie can come up with
something though.
--
Cheers,
Rich.
More information about the Libstdc++
mailing list