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

[K. G. <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.

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.

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.

FWIW,
- Kim

On Wed, Sep 3, 2008 at 11:10, Dean Michael Berris
<mik...@gm...> wrote:
> Hi Guys,
>
> I'm just thinking aloud here, but should we have explicit policies
> about the code/documentation quality?
>
> For instance, I have been remiss with inline documentation which makes
> it really hard to go back to the code and generate explicit
> relationships with existing tools. What would really help I think is
> if we started documenting each method/class/template with Doxygen
> comments.
>
> This is because now we're reaching that 'handful of developers'
> number, and it's really getting hard (even for me) to remember where
> things are and which things did what and what I should change where.
>
> I'd like to hear your thoughts about the issue, and how you propose we
> go about with generating the documentation of the source code.
>
> HTH
>
> --
> Dean Michael C. Berris
> Software Engineer, Friendster, Inc.