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.