cpp-netlib-devel

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

[Dean M. B. <mik...@gm...>]

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.

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

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

Dean,

2008/9/3 Dean Michael Berris <mik...@gm...>

> Hi Guys,
>
> I'm just thinking aloud here, but should we have explicit policies
> about the code/documentation quality?
>

Yeah, I agree.  I think its a bit broader than a doxygen policy.  Boost
itself does have some requirements:

http://www.boost.org/development/requirements.html#Documentation


> 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 much seems only reasonable, I think.  The above link described exactly
what needs to be documented for each method/class/template.


>
> 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.


Boost.Asio has some scripts which generates generates HTML from doxygen
comments and converts it to boostbook.  Some headers and examples are
included in the documentation.

http://www.boost.org/doc/libs/1_36_0/doc/html/boost_asio/reference.html

I had envisioned having something similar to this for our project.

Glyn

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

[Dean M. B. <mik...@gm...>]

On Wed, Sep 3, 2008 at 7:10 PM, Glyn Matthews <gly...@gm...> wrote:
>
> 2008/9/3 Dean Michael Berris <mik...@gm...>
>>
>> Hi Guys,
>>
>> I'm just thinking aloud here, but should we have explicit policies
>> about the code/documentation quality?
>
> Yeah, I agree.  I think its a bit broader than a doxygen policy.  Boost
> itself does have some requirements:
>
> http://www.boost.org/development/requirements.html#Documentation
>

Right. I should go take a better read of this document. :-)

>>
>> 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 much seems only reasonable, I think.  The above link described exactly
> what needs to be documented for each method/class/template.
>

Sweet. I'll go look into it.

>>
>> 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.
>
> Boost.Asio has some scripts which generates generates HTML from doxygen
> comments and converts it to boostbook.  Some headers and examples are
> included in the documentation.
>
> http://www.boost.org/doc/libs/1_36_0/doc/html/boost_asio/reference.html
>
> I had envisioned having something similar to this for our project.
>

Nice! Should we stick with non-doxygen generated documentation and do
the same thing Asio does?

Thanks for the quick response Glyn.

-- 
Dean Michael C. Berris
Software Engineer, Friendster, Inc.

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.

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

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

[K. G. <kim...@gm...>]

On Thu, Sep 4, 2008 at 13:17, Kim Gräsman <kim...@gm...> wrote:
>
> 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.[..]

... and produce :)

I meant to include a link as well -- James Shore is an XP practitioner
and spokesperson who always seems to hit the nail on the head:
http://jamesshore.com/Agile-Book/documentation.html

Cheers,
- Kim

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

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

Hi Kim,

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

> On Thu, Sep 4, 2008 at 13:17, Kim Gräsman <kim...@gm...> wrote:
>
> I meant to include a link as well -- James Shore is an XP practitioner
> and spokesperson who always seems to hit the nail on the head:
> http://jamesshore.com/Agile-Book/documentation.html
>

I (briefly) took a look and it seems like he's arguing that providing
documentation for the sake of itself doesn't work.  I hope we're taking a
more pro-active approach to documentation.  As I mentioned in my previous
response, the API and the motivation/rationale/examples need to complement
each other.  I also hope that poor documentation, as with code, is discussed
and reviewed on the mailing list so we can avoid the scenario that he
describes.

Regards,
Glyn