Re: [boost] Doxygen documentation was Re: [review] Review of Outcome (starts Fri-19-May)

Subject: Re: [boost] Doxygen documentation was Re: [review] Review of Outcome (starts Fri-19-May)
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2017-05-27 16:19:08

On Sat, May 27, 2017 at 11:09 AM, Robert Ramey via Boost <
boost_at_[hidden]> wrote:

> On 5/26/17 11:57 PM, Vicente J. Botet Escriba via Boost wrote:
>
>
>>> I believe what Robert mean is that the generated documentation of
>> Boost.Outcome using doxygen has a lot of flaws.
>> Of course it is tempting to say that it is because of doxygen.
>>
>> As you showed in the examples we can do better. Using Doxygen requires to
>> be more careful and sometimes replace some possible issues by workaroounds.
>>
>> Nevertheless Doxygen on code using the pre-processor is a nightmare. Have
>> you experience on these cases?
>>
>> I will tale a deeper look at your examples :)
>>
>>
> Or if you want to strike out on your own separate path - generally my own
> personal preference - you might consider an approach like caramel which
> would build on the idea of embedding boost book tags in comments and post
> processing the code.
>

You can also just include Quickbook docs in your source and include those
in a coherent manner in your regular quickbook docs. Since there's no
"automatic" class, function, etc. mechanics it forces you to write real
documentation in your source where it's also accessible to people just
browsing code. It also make it easier for people to contribute to your
project as they submit docs along with code changes. This approach has been
essential in getting a good number of external submissions to Predef, for
example.

-- 
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net
-- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail