Paul A. Bristow
[...]
That's what I currently do with Doxygen; all the snippets in the reference are taken from the example/ subdirectory of the project, and all those files are compiled and ran just like the other unit tests. It's really great.
Excellent! (Are they *live* links, updating the docs when you modify the example?)
Well, I currently update the documentation by hand: make gh-pages.update cd doc/gh-pages && git push The first command regenerates the doc and creates the commit on the gh-pages branch, and then I push it after a quick validation on my part. So the examples are always up-to-date, but the whole process could surely be more automatic. Something like a post commit hook could regenerate the doc, but I don't know how to set that up and I've more urgent things to do right now.
How about an alphabetic index of functions, names, words, concepts, ideas ...?
We are used to using the index in books, but they are less common in e-docs. Despite hyperlinks, navigation and search are still troublesome. I find the index really useful when dealing with the monster Boost.Math docs - and I wrote some of it!
I disabled the index because I thought the documentation was best browsed by using the type classes structure. Of course, this implies that one knows which methods are in which type class, and that's circular. I'll see if the Doxygen-generated index makes some sense and I'll re-enable it if it does.
PS For me, the library name is a big turn off - it doesn't say what the library does.
Heterogeneous combiNAtors
I see. But I still don't like it (nor do I like Fusion or Proto but that's authors rights).
Internal function names are much more important.
As Eric wisely remarks, "Names are Hard. ", but "Names are Important!"
Saying *why* is going to be vital?
Yes, I'll document that design decision and I'll change some names when it does not break the internal consistency and makes it easier for C++ers. Louis