Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-10-12 04:57:01

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Rene Rivera
> Sent: Friday, October 11, 2013 6:04 PM
> To: boost_at_[hidden]
> Subject: Re: [boost] Improving Documentation
> 
> I haven't read all of this thread.. But I find Doxygen documentation cumbersome and limited. For
my
> Predef library I decided to extend quickbook to let me more directly document the structure of
Predef.
> Which is not easy as it's *all* macro definitions. Perhaps my solutions could help the general
mixing of
> source & documentation. For example this <
> http://www.boost.org/doc/libs/1_55_0b1/libs/predef/doc/html/predef/reference/version_definition_m
> acros.html#predef.reference.version_definition_macros.boost_predef_make_macros>

I think the C++ Reference section would look very similar using Doxygen comments on the macros
themselves.  And all the BOOST_PREDEF_MAKE_0X_VRP(V) would be hyperlinks.

And the AutoIndex (macro only section if you want) would provide an alphabetical list of hyperlinks.

It's the *combination* of Doxygen with Quickbook that is the key to getting everything hyperlinked
(for use in text and C++ Reference section).  Used this way Doxygen is only a tool for generating
hyperlinks and linking them to the user provided comments on \pre \post \param \tparam \returns ...

(Doxygen soon to use Clang and probably eventually the compiler output something from the
compilation process)

Hope this makes things clearer.

Paul