Re: Doxygen - another sample, preliminary comments

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

"Phil Edwards" <pedwards@disaster.jaj.com> writes:

> On Thu, Nov 23, 2000 at 11:09:10AM +1100, Rich Churcher wrote:
> >
> > 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>
>
> It would be trivial to add --enable-doxygen (or --disable, if we
> want them done by default).  This could conditionally add a
> 'doxygen' directory to the top-level SUBDIRS in Makefile.am, and a
> doxygen/Makefile to the AC_OUTPUT list in configure.in.  That
> Makefile can do whatever we need, like running shell commands, or a
> script if it gets that complicated.

Sounds about right.  I'm not sure whether or not the documentation
generation should be on by default.  I think those people that will
most require documentation are also those who don't understand the
configure & build process too well, so perhaps --enable-doxygen is the
more appropriate default.  Experienced users can always turn it off if
they have a local copy already, or for whatever reason.


> If we need everything in a separate directory, that might be the
> easiest way to go.  If we don't, then there are some "smaller"
> solutions.

I think the separate directory is the better solution.  I'm loath to
tamper with the source any more than absolutely necessary.

On that note: perhaps we should consider using the Doxygen comment
format in future, as this will have little effect on the current
sources but will make sure any comments get included in the
documentation generation process.  For those that don't know, they
look like this:

  /// A single-line comment

  /** A multi-line 
      comment. */

Not too great a change.  It should be noted that, AFAICT, Doxygen
ignores all but the first single-line comment prior to a function or
class definition.  So, for example:

  /// assign(), a generalized assignment member function.  
  /// Two versions: one that takes a count, and one that takes a range.
  /// The range version is a member template, so we dispatch on whether
  /// or not the type is an integer.

doesn't work the way you'd expect.  To get all appropriate comments
included in the docs, we can do this:

  /// assign(), a generalized assignment member function.  
  /** Two versions: one that takes a count, and one that takes a range.
      The range version is a member template, so we dispatch on whether
      or not the type is an integer.
   */

Whether or not this is acceptable to the developers, I don't know.
It may be preferable to reproduce even these small comments in
separate files to avoid changing header content that we don't control
(like SGI's).

-- 
Cheers,
Rich.