You must be logged in to post a comment.
Thank you for accepting Hana to the incubator and giving your comments. I have
been working on fixing stuff related to some of your comments in the last few
About the name
Boost.Hana is a library of Heterogeneous combiNAtors. Of course it’s not
as descriptive as e.g. MPL, but it’s not too bad either. Also, I find it
important to have a short name (e.g. Fusion is on the long side IMO) and
one that we can remember and pronounce easily. I would also object to
putting any kind of number in the name because
1) It looks terrible (IMO)
2) Numbers should be reserved for versions (IMO)
Also, more specifically, I would object to associating Hana with the MPL by
naming it MPL2 because that would be misleading. While it supersedes both,
Hana is much closer from Fusion than MPL.
About the documentation
I am currently writing a complete user manual which explains (in particular)
the terms used in the reference. As of writing this, you can take a look at
the main page of the documentation for an explanation of type classes.
As for the documentation of e.g. `when`, I agree that it is suboptimal. If
you look at the documentation of some other members, however, you can see
that I show minimal examples. Actually, I inspired myself much of the
documentation for MPL and Fusion — I copy/pasted all the examples from
both to make sure Hana could do it all. I make it a TODO item to improve
the documentation of all members to something as clear as e.g. the zip_with
documentation for the List type class:
As for the usage of Doxygen, it makes _my_ life much easier; it is easy and
even fun to keep the documentation in a good state and up to date with the
code. It also makes the library more ‘hackable’ and easy to work with, since
you have all the information whenever you look at a header file. However, I
think I will need to tweak the output to make it fit my needs better, but that
should be possible. I’ll see what I can do about this today.
So, in summary, the documentation is still a work in progress but I expect it
to match that of Fusion in terms of quality. I thank you very much for your
comments and further discussion is definitely welcome!
I totally understand the appeal of DOxygen .
a) It’s easy to use.
b) it integrates documentation with code development
c) it embodies the “literate programming” idea which I think is a good one.
So I spent a fair amount of time looking at when I made my (personal) recommendations in the “Advice” section.
I declined to recommend it for the following reasons.
a) I didn’t see a natural or obvious way to use it to document template parameters. That is C++ concepts.
b) concepts of documentation presentation and documentation are mixed. The DocBook approach separates
these so that from the same documentation one can produce html, pdf and/or whatever else someone dreams up.
c) It doesn’t really provide a much help for really important parts of the documentation: history, tutorial, motivating
d) It encourages the practice of limiting documentation to annotating class variables and functions. Lots
of DOxygen documentation is little more that comments in the classes. This isn’t DOxygen’s fault. But
it helps programmers delude themselves in to thinking they are providing documentation when they
are really not.
I made substantial improvements to the documentation. I’m still using Doxygen,
but I tweaked its output and I think it makes the documentation much better.
The tutorial is still not completely finished, but any comments are welcome.
I’ve accepted this into the Boost Incubator as it fulfills the requirements – document and testing. Clearly you’ve put a lot of effort in to this and willing to invest more.
I’ve made a cursory examination of the documents and have a few observations. Some criticisms might be wrong because I didn’t find information in the place where I looked. Feel free to correct me on this. This is not any kind of review, just some random observations.
The name of the library is “Hana”. Generally I don’t like non-descriptive library names like phoenix, spirt, etc. The name “Hana” left me wondering what the motivation for this name might be. I didn’t see it in the documentation. For some reason I think this library is meant to be the next incarnation of mpl. mpl11 is not a great idea – but mpl2 might work. Or many something which relates to Haskel. But then the “Quick start makes it look like the next generation of boost::fusion.
Consider the documentation for boost::hana::whenat http://ldionne.github.io/hana/structboost_1_1hana_1_1when.html#details
a) If I click “More” nothing happens
b) it’s under “Classes” – but it’s a template – to me they aren’t the same
c) The detailed description says “Used to instantiate a type class base on the value of a predicate”
1) the term “Type Class” is unfamiliar to me – I presume it refers to some feature of Haskell
2) what should condition be replaced by – type fulfilling the stl concept “Predicate” or ?
3) how is this to be used. One needs a small, complete concrete motivating example.
I could go on, but I think I’ve made my point. Your documentation is no worse that that of some other boost libraries (regrettably). Consider looking into the current mpl documentation as a model and inspiration. Having said that, when I looked at Doxygen as a tool for generating documentation, I was left with the impression that it couldn’t easily meet our needs. So perhaps the usage of DOxygen is making things harder.