Hana

Library Submission

Note: you must be a logged in registered user in order to submit a library!
  • logo_linkweb_linkcomment 
    Add a row
Display Statistics
Reviews There are 0 reviews
There are 4 comments

Comment on This Page

  • Louis Dionne says:

    Robert,

    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
    days.

    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:

    http://ldionne.github.io/hana/structboost_1_1hana_1_1_list.html#a5eadaf63535ebb8cdd8d9e4c16b9bacd

    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!

    Louis

    • Robert Ramey says:

      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
      examples.
      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.

      Robert Ramey

      • Louis Dionne says:

        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.

  • Robert Ramey says:

    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.

    Robert Ramey