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

Subject: Re: [boost] [Concepts] Definition. Was [GSoC] [Boost.Hana] Formal review request
From: Robert Ramey (ramey_at_[hidden])
Date: 2014-08-12 13:57:00

Michael Levine wrote
> 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?

indeed.  This is a key part of the documentation.  It's also one of the
more difficult to make general statements about.  For this reason, 
although I've tried to make recommendations about this aspect, 
I'm not making a big deal about this.  I've been focusing on the
reference part of the documentation because it's an easier sell.
Once we can sell this, the rest will be easier.  Basically my
suggestion would be:

a) intro - purpose of the library with motivating examples.
b) more examples and advice on library usage
c) rationale - why things were done the way they were and 
not some other way
d) reference
e) acknowledgements.

But as I said - this is not (yet) part of the current crusade.

> I completely understand the extreme difficulty involved in trying to 
> enforce a specific style and format of the documentation on the library 
> authors.

I've been trying to make my case in regards to content and it's
organization.  I've consciously tried to avoid specifying style,
format, tools etc.  We have excellent examples of documentation
made with the simplest of tools - see iterators - and very hard
to use documentation made with the latest/great tools - see
boost units.  www.blincubator.com explicitly makes the case
in documentation requirements and format, tools, etc is
discussed in a totally different section - simple tools.

> 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.

I've taken great pains to address this - see above.  

>>
>> 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.

Hallelujah!!!

> 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).

It seems that "concepts lite" is shaping up to be the next episode
in an on going ten year saga.  For me it makes no difference.  If it
ever makes it and people want to use it - fine.  I even provide a table
for translating boost concept classes into concepts lite code. But
this is not really relevant to my argument.

Basically the whole concepts discussion/development has been blown
way out of proportion:

a) the important thing is that library which use parameterized types
need a method of specify and enforcing requirements on those types.
boost concept works for this concepts lite will work for this and in
fact just inserting some static asserts can work just as well for this.
(I'll be updating www.blincubator.com to demonstrate this).  

b) very few C++ programmer right now code with parameterized types.

c) even fewer publish such code.

d) even fewer explicitly specify parameter type requirements.

e) and even fewer actually include code to detect violations.

So it's beyond me that is an issue which requires some sort of
enhancement to C++ (concepts lite).  I'm sure that 1/10 the amount
of time disputing concepts would have been more than sufficient to specify
and enforce type requirements in all the boost libraries.

Just to make myself clear - the path to better library code is
for library authors to specify and verify concepts - and we already
have all we need to do that.  If the committee want's to spend
more time on this - fine - but it won't make any difference
unless library writers change their habits.

> 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 wouldn't have any objections.  I'm curious that no one has called
for compiler changes to require type requirements on template
parameters - as they are not for non-template parameters.  It's
odd to me that this hasn't come up (to my knowledge).  Not that
I'm convinced this would be a good idea.  But think about it.  I 
doubt anyone objects to the requirement that functions specify
the types of their (non-template) arguments.  And it wasn't always
so - when I started with C - function arguments types could be
omitted - in which case they defaulted to int.  This caused a lot of pain
- not all that unlike the pain that undefined template type requirements 
cause  to day.

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

Happy to hear from you - I can always use another opportunity  to flog
my case.

Robert Ramey

--
View this message in context: http://boost.2283326.n4.nabble.com/Concepts-Definition-Was-GSoC-Boost-Hana-Formal-review-request-tp4666011p4666292.html
Sent from the Boost - Dev mailing list archive at Nabble.com.