Re: [boost] [GSoC] [Boost.Hana] Formal review request

Subject: Re: [boost] [GSoC] [Boost.Hana] Formal review request
From: Louis Dionne (ldionne.2_at_[hidden])
Date: 2014-07-31 09:15:34

Paul A. Bristow <pbristow <at> hetp.u-net.com> writes:

> 
> [...]
>
> > 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