Re: [cpp-netlib-devel] [RFC] Doxygen Policy

[Glyn M. <gly...@gm...>]

Hi Kim,

2008/9/4 Kim Gräsman <kim...@gm...>

> Hi all,
>
> Personally, I'd like to keep comments and docs to an absolute minimum.
> Method comments are at best redundant and at worst misleading, IFF the
> methods are well named and well designed.
>

I disagree.  That's a pretty big IFF and since language is ambiguous, its
not realistic in my view.  Furthermore, I think its important to document
side-effect and pre-/post- conditions.  This is something that can't be done
by good naming alone.


>
> My take is to reserve comments for exceptional cases (e.g. why we
> can't test for preservation of CRLF on Windows, due to a bug in the
> Python HTTP server), and focus on naming to convey meaning (e.g. let
> test names spell out their premise).
>
> As for documentation, rationale and high-level docs tend to be more
> stable, so I'd focus on that first.  Since we're shipping a library,
> though, it makes sense to provide some detailed API documentation. Not
> sure what form is easiest to digest.


Yep.  These can be done separately.  I've added a reference section which is
where I intend to put the API docs so its bundled with the rest of the
docs.  I think they need to be provided to complement each other.  Many
boost libraries do this and I think it works.


> One benefit of Doxygen-style solutions is that the documentation is
> closer to the code, so it's easier to see and fix discrepancies. A
> drawback, on the other hand, is that huge block comments can obscure
> the actual source code.


I think the first one trumps the second one.

Glyn