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

Subject: Re: [boost] [Concepts] Definition. Was [GSoC] [Boost.Hana] Formal review request
From: Michael Levine (shmuel.levine_at_[hidden])
Date: 2014-08-12 02:07:52

On 08/05/2014 6:44 PM, Robert Ramey wrote:
>>
>> As of now, I'd say that the STL documentation provides a good starting
>> point for the documentation structure of most libraries (maybe all, I
>> don't know). But adaptations might be required to make it fit to
>> specific libraries.
>
> I make my case in
> http://rrsd.com/blincubator.com/requirements_documentation/
>
> Tutorial documentation of course is another issue so exclude that for now.

For what it's worth -- from the viewpoint of a newcomer to Boost (and 
someone who is not a developer by profession) -- I've really found the 
lack of consistency of documentation to be a major challenge in terms of 
learning what libraries are most applicable to my own needs, and how to 
use them.  I think that there are 2 separate issues involved here:

The first is layout/structure of the documentation itself, as Robert 
suggests in this and previous comments.

The second -- and from my personal experience, the more difficult -- is 
the lack of a consistently-written and sufficiently descriptive 
explanation of the 'what, where, why, and how' of the library: What does 
the library do?  Where should I use it?  Where should I not use it?  Why 
(explain the overall design -- why is the library structure like X)? How 
do I use it?

I completely understand the extreme difficulty involved in trying to 
enforce a specific style and format of the documentation on the library 
authors.  It has already been suggested -- whether one agrees with it or 
not -- that not all libraries can even fit into the same structure due 
to the paradigm mismatch.  Perhaps this suggests that an approach to 
documentation standardization should take this into account -- in terms 
of care of not over-specifying the requirements.

>
> Basically reference documentation contains a list of:
>
> named type constraints (concepts)
> types and parameterized types
> functions

 From my own perspective, the documentation I've read which has followed 
this general approach has been much easier for me to follow.

On the topic of Concepts--

The issue of Concepts is clearly quite contentious; however, what does 
seem clear to me from following this thread is that many people believe 
that Boost.Concept is lacking.  What is not clear to me is whether there 
is significant disagreement about how Boost.Concept (or its successor) 
should look/behave.  In other words- is there any consensus on what is 
expected from Boost.TypeRequirements (or whatever name might better be 
suited to Boost.Concept's successor).

Robert has been strongly advocating the use of Boost.Concept, and I 
completely hear his rationale.  As I understand, Robert's advocacy for 
Boost.Concept is that despite its shortcomings, it's currently available 
and works within its limitations.  Are there fundamental objections to 
this approach -- such that if a new Concepts/ TypeRequirements library 
was available tomorrow which alleviated the problems in Boost.Concept -- 
there wouldn't be any objections to expecting its use?

I've been following this thread for a while, and thought I'd offer my 
own thoughts on the matter.

Regards,
Michael