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
> 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
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.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk