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-18 12:54:04

Niall Douglas wrote
> On 17 Aug 2014 at 18:32, Robert Ramey wrote:
> 
>> 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
> 
> A strange location for a comment. Why not on the AFIO review page?

I have envisioned the AFIO library page as a sort of permanent running
log - similar or as a replacement for the threaded discussions on this
list. The idea is that much of the rationale and discussion is useful
to users and future maintainers of the library.  Another use would
be general reference.  On the Hana discussion there was reference
to a somewhat related discussion regarding a library proposal
many years ago - FC++. This was a functional programming system
rendered in C++.  It seems it was a "bridge too far" at the time.
But it would have been interesting to have had it around in the
incubator along with the very interesting discussion and reviews.
So far it's not working out this way - but I'm hoping that it will 
eventually take off.  We'll just have to wait and see.

I didn't see my comments as being appropriate for some permanent
record for AFIO.  Also I wanted to take my "Library Writers Workshop"
for a dry run.  My method is to just start reading the docs recording
my questions and observations as I go along.  This is fairly easy
to do - maybe a little tedious - but I think very useful.  Note that
one can't do it for his own library because he knows too much.  Hence
the design of the "Library Writer's Workshop".  Again, it's sort of
"dry run" so see how that pans out.

>> 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.
> 
> You actually made some very valid points, points which were facepalm 
> obvious. Thank you. I tried hitting reply, but there appears to be no 
> mechanism for quoting which would make a rebuttal confusing and 
> messy. 

OK - I'll try to figure out how to insert quoting.

I'm not sure that "rebuttal" is the right term.  I'm not really trying
to make an argument - but just recording my observations while
reading through.  If one gets something wrong while doing this
that either the person doing the review isn't prepared to do it
or the documentation needs some enhancement in order to
make it easier to understand.  Or maybe something just needs
fixing.  It's meant to be helpful without being directly critical.

> I can rebut here (about half your observations are already 
> answered in the docs), or am I wrong about the lack of quoting?
> 
> FYI you had some unfortunate timing, last night just after I went to 
> bed my DSL modem decided to go into a bootloop, so my CI was offline 
> till 9am this morning when I power cycled the modem. Hence all the 
> documentation was not online.
> 
> Due to continuing DSL modem instability, I am already in the process 
> of relocating AFIO documentation to be autopushed onto github after 
> each CI run, in fact I only completed the refactoring of the CI 
> innards to achieve this three weekends ago and last week was my 
> daughter's christening.

No problem.  There was enough for my cursory examination. 

>> 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.
> 
> Its two big advantages are that both Eclipse and Visual Studio will 
> show tooltips of the API doc when you hover over it, plus it has 
> exceptionally low maintenance. Otherwise I agree, it's not bad for Qt 
> C++, but not good for Boost C++. I am unaware of a superior 
> alternative in maintenance costs.

I've collected my views on documentation tools at
http://rrsd.com/blincubator.com/tools_documentation/

I much appreciate the appeal of DOxygen as far as convenience
is concerned.  I included an analysis of it for our purposes
in the above link.   Summary:
a) I like the idea of "literate programming" which DOxygen
attempts to embody.
b) I agree that they've made maintenance of reference documentation
much simpler.
c) It can work well for class libraries and functions
d) it fails utterly for templates whose type parameters are not specific
classes.
e) it makes the code headers messy and hard to read directly.
f) programmers - being basically lazy people who don't like to
write much which isn't actual code - generally end up writing
comments which just parrot the code - limiting it's utility.
It deludes programmers into thinking they are actually documenting
a library when they actually aren't
g) It doesn't address critical parts of the process such as motivation,
examples, etc.

The link above discusses the the options for creating documentation
for boost libraries.  All have been used with success.  The one
I use is XMLMind to generate boostbook xml.  Seems it's not
for everyone - but I'm happy with it.

To me this is the most valuable and interesting part of the this
discussion.  I'm less interested in AFIO in particular here than what
I view as the "right (easiest and most useful)" way to create a complete
boost quality C++ library.  I see a lot off efforts with very clever
and advanced coding in which authors have invested huge amount
of effort, which fail to get traction for lack of all the
rest of that which makes for a good library.  The whole
goal behind the incubator is to sell my ideas on how to make the
process easier so motivate authors are more likely to avoid
disappointment.  Of course these are my personal ideas - but
(lol) so far no one has posted any comments disputing them.

>> 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.
> 
> On the last point I will say this: AFIO is clean, logical and simple 
> only when compared to other asynchronous i/o libraries. The Windows 
> overlapped i/o API, libuv and of course the POSIX aio API come to 
> mind, all of which have their own weird quirks too. 

You may well be right that it can be made no simpler - I can't
defend my proposition that I think it must be possible to make it simpler.

> In other words, the lack of complexity is entirely relative to its 
> peers only. I agree that in absolute terms 98% of people needing to 
> do storage don't need async i/o. This is why AFIO will never be 
> popular enough to find a review manager.

I have used asyncio both the windows api and linux api version and have
found them to be almost unusable and very, very, very 
difficult to get right.  I very much aware of the utility of such 
a library to improve performance and to help properly factor
and decouple i/o bottle necks from the rest of the application.
I also believe that many users would find such a library very
useful and would want to use it - if it were easy enough to use.
This is the task of the library writer - to make the unusable usable.

so I would say you're not thinking big enough.  if AFIO is not simple
enough to be used within an hour of looking over the docs, it's
too complicated.

Think bigger!!!!

What would be an ideal interface ? is there a way to implement it?
For example:

main(..){

    // example one
    asyncio::istream ais("filename");  // works almost like a stream
    int x;    
    ais >> x;  // read an x
    ....
    ais.sync()

    // example two
    completion_function_object cfo = [](....);
    asyncio::istream ais("filename",  cfo);
    ais >> x;  // read an x, invoke cfo on completion

    // example three - cfo is created as an io manipulator
    ais >> x >> cfo;

    // example four - cfos and cfoy are created as io manipulators
    ais >> x >> cfox >> y >> cfoy;
}

// documentation
concept: StandardInputStream
// list off all the functions that a standard stream has to support

type
asyncio::istream<S>

type requirement: S ful fills the requirements of StandardInputStream

legal operations
ais << T 

type requirement: the operation is >> t must be valid - where is a
StandardInputStream

This is something all of can understand in a few minutes.  It would be a
hugely
popular boost library.  I personally would look forward to using it.

And you know what?  I bet you already have all the code written for it.  
Just start at the top - create some simple ref doc as above,  create
the short header for asycio::istream, and use that to redirect to the 
functions you already have.

Of course this is very speculative thoughts - its before breakfast for me
here - so feel free to take it with a kilo of salt.

Good luck with this.

Robert Ramey

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