
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:
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-F... Sent from the Boost - Dev mailing list archive at Nabble.com.