-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Robert Ramey Sent: 18 August 2014 02:33 To: boost@lists.boost.org Subject: Re: [boost] [Concepts] Definition. Was [GSoC] [Boost.Hana] Formal review request
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
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.
Short version
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. 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. Sent from the Boost - Dev mailing list archive at Nabble.com.
I had a quite different reaction while skimming these docs. It looks jolly nice ;-) It certainly looked pretty complicated - but sadly these things often are :-( I'd have put the rationale after the intro, but that's a very minor thing - you can skip over by one click. I found it easy to find what template parameters were supposed to be and do by using the C++ reference section. (Though I didn't feel the across-the-page layout made it any easier to find the item of interest). And I've like an old-fashioned alphabetic index at the end, in case I know what I was looking for. It did provide more than I probably wanted to know about some things that one might consider implementation details, but sometimes that detail is useful to understanding and for a review may be important, so it may be useful to able to navigate around the details. There is method of controlling what is visible and what is hidden (Doxygen \cond ... \endcode) and after a review, this might be worth the effort. What I take away is that: * There is no pleasing everyone all the time :-( * The format that you propose is OK for STL-like stuff, whose interface is almost trivial by comparison with this (but whose under-the-hood is deceptively complex). * But when things get complicated, it isn't enough for the job, and Doxygen is better that anything else I've yet seen. * Providing the parameter info in the Doxygen syntax has the potential to using other tools to process and display in other ways in future. * Using Doxygen to generate a C++ reference section from the main body Quickbook avoids that delusion that feeding your code into Doxygen will document it. It and Quickbook both allow you to provide lots of links to the class parameters easily, very helpful to navigate when things get complicated. * If Doxygen doesn't handle the constraints on type parameters (AKA concepts?) well, then I am fairly confident that we can get it enhanced to do this. My 2 penceworth. Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830