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?
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. 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.
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.
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 find the reverse engineered docs for Linux's KAIO async i/o API at http://www.fsl.cs.sunysb.edu/~vass/linux-aio.txt illustrative as to what I mean about API complexity. There are also a list of caveats, gotchas and quirks for using Linux KAIO at https://code.google.com/p/kernel/wiki/AIOUserGuide which AFIO makes disappear for you so you don't need to think about them [1]. 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. [1]: AFIO doesn't support the Linux KAIO API yet, we ran out of time during GSoC 2013. But the design accomodates the Linux quirks as well as it does the Windows quirks, and a lot of non-obvious effort was expended very early on to make a design which would hide platform-specific implementation detail so well. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/