Re: [boost] [Concepts] Definition. Was [GSoC] [Boost.Hana] Formal review request

Subject: Re: [boost] [Concepts] Definition. Was [GSoC] [Boost.Hana] Formal review request
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2014-08-18 13:50:02

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Robert Ramey
> Sent: 18 August 2014 02:33
> To: boost_at_[hidden]
> Subject: Re: [boost] [Concepts] Definition. Was [GSoC] [Boost.Hana] Formal
review
> request
> 
> With an eye to verifying the existence of library using templates which would
not
> benefit from explicit type constraints I went through some of the
documentation of
> AFIO.  I posted a log of my notes as I went through it
> here:
> 
> http://rrsd.com/blincubator.com/open-content/#comment-26
> 
> Of necessity, it sort of rambles around before it gets to the main point.
> That's because I had to start at the beginning in order to have enough context
to
> understand it.
> 
> Short version
> 
> a) I don't think this library demonstrates that type constraints wouldn't
help.  In fact I
> think the opposite.
> b) This further reinforces my view that DOxygen is not a great system for
writing C++
> documentation.
> c) AFIO is much more complicated than I think it has to be - but I can't prove
this
> because its so hard to understand anything about it.
> Sent from the Boost - Dev mailing list archive at Nabble.com.

I had a quite different reaction while skimming these docs.

It looks jolly nice ;-)

It certainly looked pretty complicated - but sadly these things often are :-(

I'd have put the rationale after the intro, but that's a very minor thing - you
can skip over by one click.

I found it easy to find what template parameters were supposed to be and do by
using the C++ reference section.
(Though I didn't feel the across-the-page layout made it any easier to find the
item of interest).
And I've like an old-fashioned alphabetic index at the end, in case I know what
I was looking for.

It did provide more than I probably wanted to know about some things that one
might consider implementation details,
but sometimes that detail is useful to understanding and for a review may be
important, so it may be useful to able to navigate around the details.

There is method of controlling what is visible and what is hidden (Doxygen \cond
... \endcode) and after a review, this might be worth the effort.

What I take away is that:

* There is no pleasing everyone all the time :-(

* The format that you propose is OK for STL-like stuff, whose interface is
almost trivial by comparison with this (but whose under-the-hood is deceptively
complex).

*  But when things get complicated, it isn't enough for the job, and Doxygen is
better that anything else I've yet seen.

* Providing the parameter info in the Doxygen syntax has the potential to using
other tools to process and display in other ways in future.

*  Using Doxygen to generate a C++ reference section from the main body
Quickbook avoids that delusion that feeding your code into Doxygen will document
it. It and Quickbook both allow you to provide lots of links to the class
parameters easily, very helpful to navigate when things get complicated.

* If Doxygen doesn't handle the constraints on type parameters (AKA concepts?)
well, then I am fairly confident that we can get it enhanced to do this.

My 2 penceworth.

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]