Re: Doxygen - another sample, preliminary comments

[Rich Churcher <churcher at ihug dot com dot au>]

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.