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-13 13:42:23

On 08/12/2014 1:57 PM, Robert Ramey wrote:
> 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 suppose that the question of priority depends on one's viewpoint. 
Nevertheless, I completely agree with you that the reference section 
should be the primary focus at this point.

As I'm writing this, a thought came to mind and I'll just throw it out 
there: the library index (at the documentation page - 
www.boost.org/doc/libs/1_56_0) has a short one-liner about the library. 
  I wonder if it might be possible to expand this brief summary - even 
just a bit - to provide a bit more information, about the main use case. 
  This doesn't even need to be done by the library author; just someone 
knowledgeable about the library.  I would volunteer in a flash, but I am 
absolutely clueless with neither knowledge or experience.

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

Your incubator site is a phenomenal idea and the information/directions 
that you have included there are both extremely clear and sensible.  Kudos.

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

There are quite a few dissenting opinions in this thread's history as to 
whether the same paradigms necessarily apply to Hana.  You have made 
your point clearly on the matter, but there have been quite a few 
dissenting opinions, as well.  I have my opinions on this discussion, as 
well, but it's a little off-topic from the rest of this particular 
message.  Perhaps I'll address that in a separate response, if time permits.

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

I intended my previous message as an expression of support of your 
efforts, from the perspective of a beginner/novice user.  Sometimes, 
it's hard to see that viewpoint with the level of expertise that the 
vast majority of library developers have.

>
>
>> On the topic of Concepts--
>>
<snip>
>
> 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.
That was very helpful and enlightening.

>
> Basically the whole concepts discussion/development has been blown
> way out of proportion:
I couldn't agree more.

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

Is there that much disagreement -- at least within the Boost community 
-- on this point ?  I know that Niall expressed his viewpoint that 
compiler support is essential before developers should embrace Concepts. 
  I'm not completely sure that I understand his rationale on the matter, 
and your own arguments have long ago convinced me.
Niall: Forgive me if I am misconstruing your previous comments on the 
matter.  I understood your point to be that without compiler support (in 
the form of Concepts Lite, for now), there are too many limitations with 
a Library-based system to pursue using it in code.

There was also some points regarding whether type restrictions should 
cause soft errors - being usable for SFINAE and specialization - and/or 
hard errors.  IMHO, this is a moot point: clearly there are use cases 
for each, and a requirement for Boost.Concept (or its successor - what 
I've referred to above as Boost.TypeRequirements).

Ultimately, in my own extremely limited understanding, it seems that the 
general issue here can be summarized to some extent that there are a 
wide range of expectations for a Concepts system.  I believe that you 
have been advocating what I'd characterize as the most fundamental set 
of requirements.  There is a lot more functionality and benefits that a 
fully-complete Concepts system can offer.  I can only surmise that there 
is a general reluctance to adopt a system that people feel doesn't 
achieve all of the aims that they expect from it, coupled with a concern 
for needing to revise code once language /compiler support evolves.

I'd really like to hear comments from everyone on this, and would invite 
everyone -- especially people who disagree with Robert -- to share your 
thoughts on this:
- Is my conjecture correct?  Or do those of you who object to Robert's 
position have other reasons?
- Is there anything -- short of full language support -- that you 
require in order to embrace template parameter Type Requirements?
- What are the show-stoppers in Boost.Concept that have led you to 
reject its use.

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

Unfortunately, your preaching to the choir in my case.  But I do find 
your response to provide deeper insight into the points that you have 
already written on the bl incubator site.

Best regards-
Michael Levine