Re: [Boost-users] [Review] Boost.Type Traits Extension by FredericBron

Subject: Re: [Boost-users] [Review] Boost.Type Traits Extension by FredericBron
From: Edward Diener (eldiener_at_[hidden])
Date: 2011-03-18 11:47:48

On 3/18/2011 8:37 AM, Paul A. Bristow wrote:
>
>
>> -----Original Message-----
>> From: boost-users-bounces_at_[hidden] [mailto:boost-users-
>> bounces_at_[hidden]] On Behalf Of Edward Diener
>> Sent: Thursday, March 17, 2011 2:56 PM
>> To: boost-users_at_[hidden]
>> Subject: Re: [Boost-users] [Review] Boost.Type Traits Extension by
> FredericBron
>>
>> On 3/17/2011 10:10 AM, Paul A. Bristow wrote:
>>>> -----Original Message-----
>>>> From: boost-users-bounces_at_[hidden] [mailto:boost-users-
>>>> bounces_at_[hidden]] On Behalf Of John Maddock
>>>> Sent: Thursday, March 17, 2011 11:25 AM
>>>> To: boost-users_at_[hidden]
>>>> Subject: Re: [Boost-users] [Review] Boost.Type Traits Extension by
>>> FredericBron
>>>>
>>>>> * I note that is does not use an automated system like Doxygen of
>>>>> producing the reference information.
>>>
>>>>> I would like to see the whole library Doxygen fully commented (ask
>>>>> if you think I can help) - replacing much of the current reference
> text.
>>>>
>>>> Personally I wouldn't, sorry, but I'm still not completely sold on
>>>> Doxygen
>>> :-(
>>>
>>> Well I agree that it isn't the perfect tool.
>>>
>>> (Doxygen gets confused with C++ and it's picky about linking comments
>>> to classes etc).
>>>
>>> As a user I find the current 'hand-written' alternatives deeply
>>> unsatisfactory.
>>>
>>> The bald synopsis just isn't good enough for the user.
>>>
>>> The synopsis just gives the class and function name and parameters
> types.
>>>
>>> But the user also needs to know what the parameters do, what the class
>>> or function does, what preconditions, what post conditions, what side
>>> effects, the "here be dragons" warnings, how to use it, examples ...
>>>
>>> Most of this information *has* to be hand-written - whether in plain
>>> text, or in comments of some sort.
>>>
>>> And it should all be in one place, not scattered.
>>>
>>> Only the Quickbook-Doxygen reference section seems to do this -
>>> *provided the actual code is fully commented*.
>>
>> I use doxygen, but there is nothing keeping a quickbook author from
> writing
>> hand-written comments instead. So it is incorrect to claim that "Only the
>> Quickbook-Doxygen reference section seems to do this".
>>
>> Like you I still think doxygen is good enough since the long form of
> doxygen
>> comments can be anything. But some people do find doxygen difficult, and I
> can
>> understand that. I still think that good docs go beyond just using doxygen
> and
>> need explanations in topics and good organization, and sometimes this is
> lacking
>> in Boost docs. But John Maddock's documentation is always first-rate.
>
> Indeed - the best - but I'm trying to encourage everyone to do as well, or
> better ;-)
>
> (I'm the nag behind AutoIndexing - to which challenge John has risen and
> conquered to my satisfaction - review upcoming).
>
> Just to be clear, I am NOT suggesting 'Standalone' Doxygen.
>
> I am suggesting generally using the Doxygen commands:
>
>    \class  \enum  \file \brief \details \param \tparam \pre \post \returns
> \macro
>
> and perhaps
>
>     \example \warning \remark \throws \see \typedef \var  \version
>
> and even  \deprecated ;-)
>
> Note that I said
>
> "Only the Quickbook-Doxygen reference section seems to get it should all be
> in one place, not scattered."
>
> It's the "one place, not scattered" that I think is the key here: this is
> what the Quickbook Doxygen Reference section does best.
>
> The discipline of thinking about which are suitable types of Doxygen comment
> listed above should discourage missing information (even if it means
> duplication).
>
> And the placing of documentation comments close to the code makes it easy to
> spot when these are out of step.
>
> As a user I still find that it is difficult to find even the things that I
> know exist (I remember that I wrote it!).
>
> Indexing is one aid, but it relies on the person producing the index, and in
> practice I find that searching a PDF is often the only way.
>
> Sorry to bang on about this, but too much documentation is written by
> authors who know too much, but is used by those who know too little  :-)
>
> There are some good recent examples  of improving Boost libraries in the
> pipeline.
>
> But IMO we still need to raise the bar for *user usability*.

I totall agree with you in general. But in Frederick Bron's case he 
really had to go with the method which type traits used in its 
documentation, since his work is an extension of type traits.

I find what he write in the documentation to the type traits operators 
very adequate, since it really is not complicated to understand how they 
work.

>
> Paul
>
> (PS I have to admit that type_traits is not an ideal candidate for Doxygen
> comments on account of the considerable skulduggery with MACROS required to
> get it to work.  So I can see that the effort in hiding this might be
> discouraging.)

In my variadic_macro_data library I did use doxygen to document the 
macros so I don't think having a library heavily oriented to macro use 
is an impediment to using doxygen. Of course if one is creating macros, 
to create code elements, its pretty hard to use doxygen to document 
those code elements themsleves as opposed to the macros.