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

classic Classic list List threaded Threaded
109 messages Options
1234 ... 6
Reply | Threaded
Open this post in threaded view
|

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

Eric Niebler-4
On 07/28/2014 10:20 AM, Louis Dionne wrote:
> So unless someone thinks the library isn't ready or would get rejected right
> away in its current state for reason X, I am requesting a formal review for
> Boost.Hana.
>
> Regards,
> Louis
>
> [1]: http://github.com/ldionne/hana

I see reference docs as generated by Doxygen, but I don't see user docs.
Am I missing it? That would certainly be a show-stopper.

\e


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

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

Glen Fernandes
On Mon, Jul 28, 2014 at 11:33 AM, Eric Niebler wrote:
> I see reference docs as generated by Doxygen, but I don't see user docs.
> Am I missing it? That would certainly be a show-stopper.
>
> \e

His user documentation is also via Doxygen (and looks fairly
impressive to me): http://ldionne.github.io/hana/

Glen

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

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

Eric Niebler-4
In reply to this post by Eric Niebler-4
On 07/28/2014 12:17 PM, Louis Dionne wrote:

> Eric Niebler <eniebler <at> boost.org> writes:
>> On 07/28/2014 10:20 AM, Louis Dionne wrote:
>>> So unless someone thinks the library isn't ready or would get rejected right
>>> away in its current state for reason X, I am requesting a formal review for
>>> Boost.Hana.
>>>
>>> Regards,
>>> Louis
>>>
>>> [1]: http://github.com/ldionne/hana
>>
>> I see reference docs as generated by Doxygen, but I don't see user docs.
>> Am I missing it? That would certainly be a show-stopper.
>
> As Glen points out, the tutorial is also written with Doxygen. You have to
> click on "Boost.Hana Manual" in the side bar at the left. It should also be
> the landing page when you enter the documentation at:
>
>     http://ldionne.github.io/hana/

Ah! Nice, thanks.



_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

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

Edward Diener-3
In reply to this post by Eric Niebler-4
On 7/28/2014 3:17 PM, Louis Dionne wrote:

> Eric Niebler <eniebler <at> boost.org> writes:
>
>>
>> On 07/28/2014 10:20 AM, Louis Dionne wrote:
>>> So unless someone thinks the library isn't ready or would get rejected right
>>> away in its current state for reason X, I am requesting a formal review for
>>> Boost.Hana.
>>>
>>> Regards,
>>> Louis
>>>
>>> [1]: http://github.com/ldionne/hana
>>
>> I see reference docs as generated by Doxygen, but I don't see user docs.
>> Am I missing it? That would certainly be a show-stopper.
>
> As Glen points out, the tutorial is also written with Doxygen. You have to
> click on "Boost.Hana Manual" in the side bar at the left.

I do not see this side bar on the left of your GitHub page.

> It should also be
> the landing page when you enter the documentation at:
>
>      http://ldionne.github.io/hana/

I see this online. But in your instructions on your GitHub page you say
there is an offline version in the doc/gh-pages of your library but the
index.html there only shows the doxygen documentation.

>
> The tutorial goes through the basic concepts used everywhere in the library
> and then explains how to use the reference documentation (accessible by
> clicking "Reference" on the left panel). Perhaps you have already seen that
> but it did not qualify as a tutorial to you? That would be valid criticism.
>
> The documentation was built with Boost.Fusion as a model, i.e. a short primer
> and then a thorough reference with examples of how to use each component.
> I thought this was the best way to go given the nature of the library (a lot
> of general purpose utilities and very little room for surprise).
>
> Please let me know if you think the documentation is not adequate (or
> anything else for that matter).
>
> Regards,
> Louis



_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

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

Edward Diener-3
On 7/28/2014 4:37 PM, Louis Dionne wrote:

> Edward Diener <eldiener <at> tropicsoft.com> writes:
>
>>
>> On 7/28/2014 3:17 PM, Louis Dionne wrote:
>>>
>>> [...]
>>>
>>> As Glen points out, the tutorial is also written with Doxygen. You have to
>>> click on "Boost.Hana Manual" in the side bar at the left.
>>
>> I do not see this side bar on the left of your GitHub page.
>
> The side bar is in the documentation at
>
>      http://ldionne.github.io/hana
>
> , not on the GitHub page of the project itself.

I do see that.

>
>
>>> It should also be
>>> the landing page when you enter the documentation at:
>>>
>>>       http://ldionne.github.io/hana/
>>
>> I see this online. But in your instructions on your GitHub page you say
>> there is an offline version in the doc/gh-pages of your library but the
>> index.html there only shows the doxygen documentation.
>
> Just to make sure; did you do
>
>      git submodule update --init --remote

C:\Programming\VersionControl\modular-boost\libs\hana>git submodule
update --init --remote
Submodule path 'doc/gh-pages': checked out
'68817a886f0f13d286b28f27e4462694b37522b9'

I do now see the full manual. This is what I need to understand your
library. Just a doxygen reference with examples never does anything for
me <g>.

>
> at the root of your local clone, as instructed in the README? This checks out
> the doc/gh-pages submodule at its latest version. What I suspect you did is
> clone the project and then `git submodule init`, which would have left you
> with some fairly old version of the documentation.
>
> The `--remote` option must be added because the master branch only tracks the
> submodule at a given commit. I know of two solutions for this:
>
>      1. Use `git submodule update --init --remote` instead of the usual
>         `git submodule update --init` to check out the latest version of
>         the documentation.
>
>      2. Update the commit of the submodule referenced by the master branch
>         every time we regenerate the documentation in order to make
>         `git submodule update --init` equivalent to
>         `git submodule update --init --remote`.
>
> I went for the first option because I did not want to make a commit in master
> each time I updated the documentation. What I'll try to do for now is change
> the contents of doc/gh-pages that you get by default and put a note saying
>
>      "Here's the command you should do if you want the documentation offline"
>
> Does that seem reasonable?

A separate branch with the latest full documentation , maybe called
'doc' might be clearer.


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

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

Louis Dionne
Edward Diener <eldiener <at> tropicsoft.com> writes:

>
> [...]
>
> A separate branch with the latest full documentation , maybe called
> 'doc' might be clearer.

There is such a branch, and it's called `gh-pages`. It's the way of doing
things for projects on GitHub. The problem with providing the documentation
_only_ through a branch is that you have to check it out (and hence overwrite
the current working directory) to see it. So what I did is create such a
branch and then make it available through a submodule, so you can check out
that branch in a subdirectory.

Louis



_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

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

Louis Dionne
Louis Dionne <ldionne.2 <at> gmail.com> writes:

>
> Edward Diener <eldiener <at> tropicsoft.com> writes:
>
> >
> > [...]
> >
> > A separate branch with the latest full documentation , maybe called
> > 'doc' might be clearer.
>
> There is such a branch, and it's called `gh-pages`. It's the way of doing
> things for projects on GitHub. The problem with providing the documentation
> _only_ through a branch is that you have to check it out (and hence overwrite
> the current working directory) to see it. So what I did is create such a
> branch and then make it available through a submodule, so you can check out
> that branch in a subdirectory.

Okay, so I made some changes and here's how it works now:

  1. If you clone the repository as instructed in the README, everything
     just works.

  2. If you clone the repository and then just checkout the submodule, but
     not at its latest version, you get an empty directory with a README
     telling you exactly the commands to get the latest documentation.

  3. When I release stable versions of the library, the default checkout
     of the documentation submodule will be the documentation for that
     version of the library instead of an empty directory with a README,
     as one would expect.

Louis



_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

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

Edward Diener-3
On 7/28/2014 8:26 PM, Louis Dionne wrote:

> Louis Dionne <ldionne.2 <at> gmail.com> writes:
>
>>
>> Edward Diener <eldiener <at> tropicsoft.com> writes:
>>
>>>
>>> [...]
>>>
>>> A separate branch with the latest full documentation , maybe called
>>> 'doc' might be clearer.
>>
>> There is such a branch, and it's called `gh-pages`. It's the way of doing
>> things for projects on GitHub. The problem with providing the documentation
>> _only_ through a branch is that you have to check it out (and hence overwrite
>> the current working directory) to see it. So what I did is create such a
>> branch and then make it available through a submodule, so you can check out
>> that branch in a subdirectory.
>
> Okay, so I made some changes and here's how it works now:
>
>    1. If you clone the repository as instructed in the README, everything
>       just works.
>
>    2. If you clone the repository and then just checkout the submodule, but
>       not at its latest version, you get an empty directory with a README
>       telling you exactly the commands to get the latest documentation.
>
>    3. When I release stable versions of the library, the default checkout
>       of the documentation submodule will be the documentation for that
>       version of the library instead of an empty directory with a README,
>       as one would expect.

This is reasonable.

But I do not understand from your documentation how your library relates
to Boost MPL. The Boost MPL library is about manipulating and creating
types at compile time, and creating logic paths again at compile time to
manipulate types. All of this is encapulated by the MPL's notion of
metafunctions to do compile-time programming. But I cannot get from your
documentation any of the MPL equivalence of how any of this is done with
your library. Is your library meant to duplicate/replace this MPL
functionality in some way ? Or is it meant to do something else entirely
not related to compile-time programming ?

I am only asking this because I had been told that your library is at
the the least a replacement for MPL compile-time type manipulation
functionality using C++11 on up.


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

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

Niall Douglas
On 28 Jul 2014 at 23:03, Edward Diener wrote:

> But I do not understand from your documentation how your library relates
> to Boost MPL. The Boost MPL library is about manipulating and creating
> types at compile time, and creating logic paths again at compile time to
> manipulate types. All of this is encapulated by the MPL's notion of
> metafunctions to do compile-time programming. But I cannot get from your
> documentation any of the MPL equivalence of how any of this is done with
> your library. Is your library meant to duplicate/replace this MPL
> functionality in some way ? Or is it meant to do something else entirely
> not related to compile-time programming ?
>
> I am only asking this because I had been told that your library is at
> the the least a replacement for MPL compile-time type manipulation
> functionality using C++11 on up.
I think a table with MPL98 forms on one side and Hana equivalents on
the other would be an enormous help with the learning curve.

Also, regarding formal review, I personally would feel uncomfortable
accepting a library that only works with a single version of clang. I
would feel much happier if you got trunk GCC working, even if that
means workarounds.

BTW some of those graphs you had in C++ Now showing time and space
benchmarks of performance would be really useful in the docs, maybe
in an Appendix. When MSVC eventually gets good enough that Hana could
be ported to it (VS2015?) I think it would be fascinating to see the
differences. I'm sure Microsoft's compiler team would also view Hana
as an excellent test of future MSVCs, indeed maybe Stephan could have
Hana used as an internal test of conformance for the team to aim for.

I'd also like to see unit testing that verified that the current
compiler being tested has a time and space benchmark curve matching
what is expected. It is too easy for code to slip in or the compilers
themselves to gain a bug which creates pathological metaprogramming
performance. Better to have Travis CI trap that for you than head
scratching and surprises later.

I'd like to see some mention in the docs of how to use Hana with that
metaprogramming debugger from that German fellow. He presented at a
C++ Now.

Finally, there are ways and means for doxygen docs to automatically
convert into BoostBook docs. You'll need to investigate those before
starting a formal review. Tip: look into how Geometry/AFIO does the
doxygen conversion, it's brittle but it is easier than the others.

Niall

--
ned Productions Limited Consulting
http://www.nedproductions.biz/ 
http://ie.linkedin.com/in/nialldouglas/




_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

SMime.p7s (8K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Niall Douglas
On 29 Jul 2014 at 11:04, Niall Douglas wrote:

> I'd like to see some mention in the docs of how to use Hana with that
> metaprogramming debugger from that German fellow. He presented at a
> C++ Now.

Apologies, the fellow is in fact Hungarian.

Actually, there are no less than *two* such Hungarians, both with
tools solving the problem from different ways. One is Zoltán
Porkoláb, the other is Ábel Sinkovics. The former presented at C++
Now 2013, the latter at C++ Now 2014.

Thanks to Benedek for correcting me.

Niall

--
ned Productions Limited Consulting
http://www.nedproductions.biz/
http://ie.linkedin.com/in/nialldouglas/




_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

SMime.p7s (8K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Gonzalo BG
The documentation is awesome, thanks! I liked the inline discussions that
relate the library with Fusion and MPL, and in particular your use of
variable templates (e.g. type<>).

>I would feel much happier if you got trunk GCC working, even if that
means workarounds.

I'd rather wait till GCC offers basic C++14 support for variable templates
and rel. constexpr before even attempting this since otherwise this looks
like a major undertaking for little win: those who can use gcc-trunk can
probably also use clang-trunk and anyhow these users are a minority
anyways. IMO compilers will get there in due time.




On Tue, Jul 29, 2014 at 12:36 PM, Niall Douglas <[hidden email]>
wrote:

> On 29 Jul 2014 at 11:04, Niall Douglas wrote:
>
> > I'd like to see some mention in the docs of how to use Hana with that
> > metaprogramming debugger from that German fellow. He presented at a
> > C++ Now.
>
> Apologies, the fellow is in fact Hungarian.
>
> Actually, there are no less than *two* such Hungarians, both with
> tools solving the problem from different ways. One is Zoltán
> Porkoláb, the other is Ábel Sinkovics. The former presented at C++
> Now 2013, the latter at C++ Now 2014.
>
> Thanks to Benedek for correcting me.
>
> Niall
>
> --
> ned Productions Limited Consulting
> http://www.nedproductions.biz/
> http://ie.linkedin.com/in/nialldouglas/
>
>
>
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

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

Louis Dionne
In reply to this post by Edward Diener-3
Edward Diener <eldiener <at> tropicsoft.com> writes:

>
> [...]
>
> But I do not understand from your documentation how your library relates
> to Boost MPL. The Boost MPL library is about manipulating and creating
> types at compile time, and creating logic paths again at compile time to
> manipulate types. All of this is encapulated by the MPL's notion of
> metafunctions to do compile-time programming. But I cannot get from your
> documentation any of the MPL equivalence of how any of this is done with
> your library. Is your library meant to duplicate/replace this MPL
> functionality in some way ? Or is it meant to do something else entirely
> not related to compile-time programming ?

I had started to reply with a lengthy explanation of how it works, but that
would not fix the problem because it is now clear that my documentation _is_
the problem. I'll improve it, make it more explicit and then post back.


> I am only asking this because I had been told that your library is at
> the the least a replacement for MPL compile-time type manipulation
> functionality using C++11 on up.

It is, and it's also a replacement for Fusion and hence many other
metaprogramming utilities. In particular, I'll write a cheatsheet
showing how to do everything in the MPL and everything in Fusion
with Hana.


Thank you for taking the time to read the documentation (I assume you did)
and give me your feedback.

Regards,
Louis



_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

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

Louis Dionne
In reply to this post by Niall Douglas
Niall Douglas <s_sourceforge <at> nedprod.com> writes:

>
> [...]
>
> I think a table with MPL98 forms on one side and Hana equivalents on
> the other would be an enormous help with the learning curve.

Will do.


> Also, regarding formal review, I personally would feel uncomfortable
> accepting a library that only works with a single version of clang. I
> would feel much happier if you got trunk GCC working, even if that
> means workarounds.

That would mean a lot of workarounds. TBH, I think the "right" thing
to do is to push the compiler folks to support C++14 (and without bugs, plz)
as soon as possible. The reason I am so unwilling to do workarounds is that
_the whole point_ of Hana is that it's cutting edge. Whenever you remove a
C++14 feature, Hana goes back to the stone-age performance of Fusion/MPL
and becomes much, much less usable. Why not use Fusion/MPL in that case?


> BTW some of those graphs you had in C++ Now showing time and space
> benchmarks of performance would be really useful in the docs, maybe
> in an Appendix. When MSVC eventually gets good enough that Hana could
> be ported to it (VS2015?) I think it would be fascinating to see the
> differences. I'm sure Microsoft's compiler team would also view Hana
> as an excellent test of future MSVCs, indeed maybe Stephan could have
> Hana used as an internal test of conformance for the team to aim for.

Yup, I have a benchmark suite for Boost.Hana, like I had for the MPL11.
I have started integrating them with the documentation, but I'm not sure
what's the best way of doing it so I did not push forward on that.

Basically, I got a benchmark for almost every operation of almost every
sequence that's supported by Hana (including those adapted from external
libraries), but I'm not sure yet of how to group them in the documentation
(per operation? per sequence? per type class?).

The problem is made worse by two things:

  - It only makes sense to benchmark components that are isomorphic. For
    example, what does it mean to benchmark a std::tuple against a
    mpl::vector? Not much, because the price you pay for std::tuple
    gives you the ability to hold values, whereas mpl::vector can only
    hold types. We don't want to compare apples with oranges, and the
    grouping of benchmarks should be influenced by that.

  - How do we handle different compilers? Right now, all benchmarks are
    produced only on Clang, which is OK because it's the only compiler that
    can compile the library. When there is more than one compiler, how do we
    generate the benchmarks for all of them, and how do we integrate the
    benchmarks in the documentation?


> I'd also like to see unit testing that verified that the current
> compiler being tested has a time and space benchmark curve matching
> what is expected. It is too easy for code to slip in or the compilers
> themselves to gain a bug which creates pathological metaprogramming
> performance. Better to have Travis CI trap that for you than head
> scratching and surprises later.

I thought about doing this, but I did not because I thought it was a HUGE
undertaking to automate it. I think we're better off integrating the
benchmarks in the documentation and then when something is really weird,
we just have to look at the generated benchmarks and see what's wrong.
If someone can suggest a way to do it automatically that won't take me weeks
to set up, I'm interested.

Also, I wouldn't want to slip in the trap of testing the compiler; testing
Hana is a large enough task as it is (341 tests + 165 examples as we speak).


> I'd like to see some mention in the docs of how to use Hana with that
> metaprogramming debugger from that German fellow. He presented at a
> C++ Now.

I'll think about something; that's a good idea. Thanks.


> Finally, there are ways and means for doxygen docs to automatically
> convert into BoostBook docs. You'll need to investigate those before
> starting a formal review. Tip: look into how Geometry/AFIO does the
> doxygen conversion, it's brittle but it is easier than the others.

Is it mandatory for a Boost library to have BoostBook documentation?
I'd like to stay as mainstream as possible in the tools I use and reduce
the number of steps in the build/documentation process for the sake of
simplicity. Is there a gain in generating the documentation in BoostBook?


Regards,
Louis



_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

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

pabristow
> -----Original Message-----
> From: Boost [mailto:[hidden email]] On Behalf Of Louis Dionne
> Sent: 29 July 2014 18:03
> To: [hidden email]
> Subject: Re: [boost] [GSoC] [Boost.Hana] Formal review request
> Is it mandatory for a Boost library to have BoostBook documentation?
> I'd like to stay as mainstream as possible in the tools I use and reduce
> the number of steps in the build/documentation process for the sake of
> simplicity. Is there a gain in generating the documentation in BoostBook?

It certainly isn't compulsory, but it gives it a Boosty look'n'feel that will
probably make it easier for Boost users to navigate.

For Boost, Quickbook, Boostbook, Doxygen *is* mainstream ;-)

IMO, the nicest docs start with Quickbook, an easy but very powerful 'markup
language'.

You can use all your Doxygen comments in your code to provide a C++ reference
section with no extra work.

And you can prepare automatic indexes that help user find their way around.

Tell me if I can help.

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
+44 (0) 1539 561830










_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

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

Glen Fernandes
In reply to this post by Louis Dionne
On Tue, Jul 29, 2014 at 10:02 AM, Louis Dionne wrote:
>
> That would mean a lot of workarounds. TBH, I think the "right" thing
> to do is to push the compiler folks to support C++14 (and without bugs, plz)
> as soon as possible. The reason I am so unwilling to do workarounds is that
> _the whole point_ of Hana is that it's cutting edge. Whenever you remove a
> C++14 feature, Hana goes back to the stone-age performance of Fusion/MPL
> and becomes much, much less usable. Why not use Fusion/MPL in that case?
>

I agree.

> Is it mandatory for a Boost library to have BoostBook documentation?
> I'd like to stay as mainstream as possible in the tools I use and reduce
> the number of steps in the build/documentation process for the sake of
> simplicity. Is there a gain in generating the documentation in BoostBook?

It is not mandatory as far as I know. [It was rightly mandatory for
Boost.Align because my documentation was essentially a single giant
index.html :-) ].

In my opinion your current documentation looks nicer, and more modern,
than most existing Boost library documentation]. The only case I can
see for BoostBook would be visual consistency with existing Boost
documentation.

Glen

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

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

cppljevans
In reply to this post by Gonzalo BG
On 07/29/2014 11:10 AM, Gonzalo BG wrote:

> The documentation is awesome, thanks! I liked the inline discussions that
> relate the library with Fusion and MPL, and in particular your use of
> variable templates (e.g. type<>).
>
>> I would feel much happier if you got trunk GCC working, even if that
> means workarounds.
>
> I'd rather wait till GCC offers basic C++14 support for variable templates
> and rel. constexpr before even attempting this since otherwise this looks
> like a major undertaking for little win: those who can use gcc-trunk can
> probably also use clang-trunk and anyhow these users are a minority
> anyways. IMO compilers will get there in due time.
>
>
I agree.  I can certainly understand Louis' reluctance.
All that effort to adapt to old compilers would be useless
as soon as the those compilers upgrade, and hana would
provide them (as already mentioned) with more incentive to
upgrade.
[snip]



_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

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

Nate Crookston
In reply to this post by Eric Niebler-4
Hi Louis,

Louis Dionne wrote:

> Dear Boost,
>
> It has been a while since I've given news about my GSoC project,
> Boost.Hana[1].
> Things are going very well and I uploaded the library to the Boost
> Incubator.
> I think it is time to push the library forward for review.


I've looked through much of the documentation, and this looks really good.
I was impressed with your post on improved performance using lambdas, but I
was concerned about it being very cumbersome.  I really like the syntax
you've developed.

Regarding performance, I note that you have several graphs in the reference
section showing (generally) good performance scaling.  I think it would be
useful to add a section to the manual speaking generally about
performance.  One common criticism of metaprogramming is the time it takes
to compile and link.  Addressing it would certainly help someone understand
more benefits of the library without having to follow the boost list.

I have a few other suggestions about the documentation that I can send
along, if you're looking for that at this point.

As the author, I know everything that's left to be done and polished before
> I can be fully satisfied. Still, I believe the library is worthwhile in its
> current state as it implements a superset of the functionality found in the
> Boost.MPL and Boost.Fusion. I also think the library will benefit greatly
> from a larger user base and more feedback.
>

It sounds like you're already planning to do this, but mentioning
type_list<>, even if it's essentially just list(type<>...) would help show
that this is a valid replacement for MPL.

Do you plan to implement things like MPL's vector_c?  I ask because a C++14
units library could be much nicer than the (already nice) boost units
library.  Using Hana could be nice for compile times.


> Here are some caveats:
> - The library requires a full C++14 compiler, so only Clang 3.5 can compile
>   the unit tests right now. However, compilers will eventually catch up.
>   Also, pushing cutting edge libraries forward might motivate compilers to
>   support C++14 ASAP, which is probably a good thing.
>

I would have no problem with a C++14-only requirement.  It would definitely
slow adoption, but I'd rather the code stay more pure and performant.  As
others have noted, we have fallbacks.

My only concern would be the performance on other compilers once they
implement the necessary features.  Is there some assurance that the lambda
trick would work (i.e. be fast) on g++?

I look forward to playing with this in about a month.  I'll definitely post
a review if and when a review occurs.

Thanks,
Nate

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

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

cppljevans
In reply to this post by Eric Niebler-4
On 07/28/2014 12:20 PM, Louis Dionne wrote:
> Dear Boost,
>
> It has been a while since I've given news about my GSoC project, Boost.Hana[1].
[snip]
> [1]: http://github.com/ldionne/hana
>
Hi Louis,

I looked at:

http://ldionne.github.io/hana/index.html

but saw no mention of the `let-expressions` that was mentioned here:

http://article.gmane.org/gmane.comp.lib.boost.devel/245231

Did I miss where they are documented or was there some problem
in implementing them and, consequently, they were left out?

-regards,
Larry



_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

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

Robert Ramey
In reply to this post by Eric Niebler-4
Jul 29, 2014; 3:04am  Niall Douglas Niall Douglas
On 28 Jul 2014 at 23:03, Edward Diener wrote:

>> But I do not understand from your documentation how your library relates
>> to Boost MPL. The Boost MPL library is about manipulating and creating
>> types at compile time, and creating logic paths again at compile time to
>> manipulate types. All of this is encapulated by the MPL's notion of
>> metafunctions to do compile-time programming. But I cannot get from your
>> documentation any of the MPL equivalence of how any of this is done with
>> your library. Is your library meant to duplicate/replace this MPL
>> functionality in some way ? Or is it meant to do something else entirely
>> not related to compile-time programming ?
>>
>> I am only asking this because I had been told that your library is at
>> the the least a replacement for MPL compile-time type manipulation
>> functionality using C++11 on up.

>I think a table with MPL98 forms on one side and Hana equivalents on
>the other would be an enormous help with the learning curve.

+1

>Also, regarding formal review, I personally would feel uncomfortable
>accepting a library that only works with a single version of clang. I
>would feel much happier if you got trunk GCC working, even if that
>means workarounds.

-1

I would disagree.  Boost has always required conformity with the latest
C++ standard - current compilers be damned.  Of course a number of
libraries don't make much sense if they're not widely compilable
and those authors have accommodated this.  But a library such as
this doesn't require such a wide compatibility to be useful.  No
one is going to rip out the mpl in a current library and replace
it with hana.  A newer app or library will (should) be using a
current compilers and just hana from the start.  So I think any
requirement/request support some older compiler is needlessly
burdensome and not worth the effort.  Were hana to get accepted,
it wouldn't appear in boost for at least a year and by that time
C++14 should be available to anyone who want's to depend upon it.

>I'd also like to see unit testing that verified that the current
>compiler being tested has a time and space benchmark curve matching
>what is expected. It is too easy for code to slip in or the compilers
>themselves to gain a bug which creates pathological metaprogramming
>performance. Better to have Travis CI trap that for you than head
>scratching and surprises later.

I would also like to see a test dashboard of some sort implemented.
Especially since it's unclear which compilers can compile this thing.

>I'd like to see some mention in the docs of how to use Hana with that
>metaprogramming debugger from that German fellow. He presented at a
>C++ Now.

lol - well there's lot's of things I'd like to see - but I think it's
not a great idea to request/require some feature/support which depends
upon something that isn't in boost and might require significant work
to add.  Let's make it work before we make it better.

Jul 29, 2014; 9:10am  Gonzalo BG Gonzalo BG wrote

>The documentation is awesome, thanks! I liked the inline discussions that
>relate the library with Fusion and MPL, and in particular your use of
>variable templates (e.g. type<>).

awesome is way too generous. needs work.

On Tue, Jul 29, 2014 at 10:02 AM, Louis Dionne wrote:

> Is it mandatory for a Boost library to have BoostBook documentation?
> I'd like to stay as mainstream as possible in the tools I use and reduce
> the number of steps in the build/documentation process for the sake of
> simplicity. Is there a gain in generating the documentation in BoostBook?

It's not mandatory as far as I know either.  Boost documentation is all
over the place - from terrible to incredible.  And documentation tools have
evolved.  Library authors haven't often migrated tools once the documentation
is done. You DOxygen is a lot better than most I've seen. Misc notes regarding
boost documentation.

a) In the beginning, boost documentation was just html - a lot of still is just
that - e.g. serialization library.  

b) Then came along BoostBook.  Very attractive
because it decoupled documentation content from the formatting which allows
the creation of PDF and HTML from the same "source".  It was on the DocBook "wave"
and seemed the way of the future.  The tool chain was a pain to setup (and still
likely is), but once, set up works pretty well.

c) But BoostBook was a pain to edit - then came along QuickBook which defined it's
own markup (yet another one!) but produced DocBook source.  This addressed
the BoostBook editing pain but left the BoostBook advantages.  The first workable
combination which addressed most needs.

d) Some libraries (e.g Geometry, Units) have incorporate DOxygen into this mix
due the convenience of including the reference information along with the code.
Basically this amounts to a poor man's literate programming system.  This is
a lot easier for the programmer than trying to maintain two separate markups.

e) Somewhere along the line Eric Niebler, let lose an email along the lines of
"I can't stand it any more" criticizing boost documentation.  Nothing much came
of it, but it did affect me and convinced me that what we needed was more formal
usage of C++ concepts and requirement that new libraries implement and document
them where appropriate.  I've been flogging this when/where I can - most recently
in the Boost Incubator pages.  So far, I haven't made much head way yet, but I'm
only 66 so this won't go away for some time yet.

Looking at your documentation, I realize now that you've implemented C++ concepts
under the name TypeClasses (sounds vaguely familiar from the 20 times I read the
haskel book trying to figure out what a monad is).  And you have fairly extensive
information about what TypeClass means - it means C++ concept / type requirement.  
I would have much preferred that you had explicitly used boost concept check library.
I don't know if your code actually checks the concepts.  And I have questions about
particular concepts: e.g. Searchable - as opposed to more basic traits - we'll
arm wrestle over that later.

Given that boost has had no explicit requirements for documentation toolset
it would be unfair to start imposing them ex-post facto.  So I would say
if you can get the content of the documentation to pass the review - we'd
could live with your DOxygen version - even though I personally don't like it.

So the more I look at this the more I like and the more work I think it needs.

Robert Ramey
Reply | Threaded
Open this post in threaded view
|

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

Paul Fultz II
In reply to this post by Eric Niebler-4
Awesome library! Here are some of my thoughts on the library.

It seems like you are bringing haskell to C++. However, in the past,
functional libraies seem to struggle with acceptance in boost. It seems like
it would be nicer to name and organize things in a way that is familiar to C++
programmers. One of the things that helped make it easy for me when I firsted
learned Boost.MPL, was it was built around the STL interface. I understand in
Boost.Hana, you don't use iterators for performance, but it still could be
organized in a way that is more familiar to C++ programmers(Some places I've
worked, there was resistance to even using Boost.Fusion, which is built around
familiar C++ interfaces. Imagine if I tried to introduce Boost.Hana.)

Here's a few list of names off the top of my head that could use more C++-like
names:

foldl = fold
foldr = reverse_fold
fmap = transform
cons = push_front
scons = push_back
datatype = tag,tag_of
head = front
last = back
typeclass = concept

Also, most C++ programmers are used to seeing libraries divided into
containers and algorithms, whereas Boost.Hana seemed to be built around
haskell-like interfaces. As C++ programmers, its difficult to find where to
look for functionality. Ideally, it would be nice to start with simple
concepts, such as iteration, and then have algorithms built on top of that.
And then have a mechanism to overload algorithms to improve the performance
for certain sequences(for example `mpl::vector` algorithms could be
specialized to improve compile time performance).

It seems like you can overload the algorithms in your library, but its spread
across different typeclasses. And then the `List` typeclass has a bunch of
algorithms in them. Since, `List` is heavy, I can't split the specializations
of these algorithms across several header files, for example. It would be
better to have smaller and simpler concepts. However, the specializations of
these concepts should be for advance use of the libraries. It should start
with some simple concepts to get people to start using the library, and then
if someone wants to create an optimized `reverse_fold`, they could.

It would be nice to see the docs divide into something like:

- The basic type concepts(such as `type<>`, integral constants, metafunctionn,
  etc)

- The basic sequence concepts, what concepts are necessary to define a hana
  sequence, and the different sequences

- Accessing data from a hana sequence, such as `at`, `front`, `back`

- Views or adaptors on sequences, such as filter, transform

- Algorithms on sequences, such as `fold`, `max`, etc

- Extending Boost.Hana

Those are some thoughts after reading through the library. Perhaps, I missed
some design goals you have.
1234 ... 6