Boost logo

Boost Users :

Subject: Re: [Boost-users] [boost] [Fit] formal review starts today
From: Paul Fultz II (pfultz2_at_[hidden])
Date: 2016-03-07 00:15:11


On Sunday, March 6, 2016 at 9:42:19 PM UTC-6, Edward Diener wrote:
>
> On 3/3/2016 6:43 AM, Vicente J. Botet Escriba wrote:
> > Dear Boost community, sorry for the late anounce
> >
> > The formal review of Paul Fultz II's Fit library starts today, 2nd March
> > and ends on 13th March.
> >
> > Fit is a header-only C++11/C++14 library that provides utilities for
> > functions and function objects.
>
> These are some comments/queries about the Fit documentation.
>
> Introduction
>
> The introduction says that Fit "provides utilities for functions and
> function objects." But it seems as if Fit works only with lambda
> functions and function objects.

Fit works with any generalized Callable:

http://en.cppreference.com/w/cpp/concept/Callable
 

> The term 'function' normally encompasses
> a much larger definition in C++ which includes global functions, static
> functions, member functions, and lambda functions.

Which is what Callable encompasses, but I used "function" since more
people are familiar with that than Callable.
 

> Fit needs to be more
> precise in what it says it works with. It repeatedly refers to function
> objects and lambda functions as 'functions'. I think this vagueness of
> terminality is really confusing in the documentation.
>

Perhaps, I should refer to the Callable concept early on then.
 

>
> Quick Start:Function Objects
>
> "We can make it behave like a regular function if we construct the class
> as a global variable."
>
> What about a non-global
>
> sum_f sum = sum_f();
>
> makes 'sum' not behave like a regular function other than the fact that
> the variable 'sum' may eventually go out of scope ?
>

In C++, a regular function is always global, there is no such thing as local
function(sans gcc extensions).
 

>
> Quick Start:Lambdas
>
> Why do we need both BOOST_FIT_STATIC_LAMBDA and
> BOOST_FIT_STATIC_LAMBDA_FUNCTION ? I would seem that
> BOOST_FIT_STATIC_LAMBDA_FUNCTION would be adequate and
> BOOST_FIT_STATIC_LAMBDA is just redundant, mimicking lambda syntax to no
> purpose.
>

BOOST_FIT_STATIC_LAMBDA_FUNCTION and BOOST_FIT_STATIC_FUNCTION both define a
function at global scope, and can only be used at global scope, whereas
BOOST_FIT_STATIC_LAMBDA can be used to constexpr initialize local variables
as
well. In fact, BOOST_FIT_LIFT uses this since it is not always clear what
context the user might call BOOST_FIT_LIFT.
 

>
> Quick Start:Overloading
>
> The overloading adaptors show two or more lambda functions. Can they
> also work with function objects ? Or a mix of lambda functions and
> function objects ? In fact all the reamining Quick Start topics show
> examples with lambda functions. Do they also work with function objects ?
>

Yes it can be used with function objects. I probably should show an example
of
that as well. I used the lambdas because of the terseness of them.
 

>
> Quick Start:Variadic
>
> I do not understand what 'We can also make this print function varidiac,
> so it prints every argument passed into it.' means ?
>

I'll try to explain that better, but basically it will print each argument,
so:

print("hello", 5); // Will print "hello" and 5
 

>
> I do not think the Quick Start explains very much since it is dealing
> with adaptors of which we know almost nothing and the explanation for
> these adaptors and what they actually do is very terse.

Probably can expand the explanation of adaptors a little more.
 

> I realize that
> is why it is called a 'Quick Start' is because it is just giving the
> end-user a quick review of the sort of functionality that the library
> entails, but I would much rather see a good Overview first before I look
> at anything else in the documentation.
>
> More Examples
>
> The more examples section looks at useful cases for the library. Since I
> haven't had an overview for the library yet it is disappointing that
> this section comes before I really understand how the library is
> organized with at least general functionality. I am now given a series
> of some highly complicated library syntax without the least idea of why
> any of this syntax should be as it is, what it means, or how it works.
> That doesn't convince me to use the library at all. It just convinces me
> that the library has some showy functionality which does clever things
> for particular use cases which the library author wants to convince me I
> am going to encounter in my own programming.
>

Probably more explanation about each of the components used to build
the example will be helpful.
 

>
> Overview
>
> The overview section consists of explaining what a function adaptor,
> static function adaptor, and decorator are. It also give me some notes
> about the syntax of the documentation. I would call this section
> 'Definitions' and "Documentation Syntax'. One thing it is not is an
> overview of the Fit library as far as I can understand what an overview
> is. I also note that following large scale sections deal in Adaptors,
> Decorators, Functions, and Utilities. Since 'Functions' and 'Utilities'
> are not "defined" in this Overview I am left to wonder if 'Functions'
> and 'Utilities' just mean anything in the library which is not an
> adaptor or a decorator, and what distinguishes a function from a utility.
>

This is a good point, the current overview should be called "Definitions".
 

>
> In the 'Signatures' section of the Overview I read:
>
> "All the functions are global function objects except where an explicit
> template parameter is required." I honestly don't know what this is
> supposed to mean. Does this refer to when function objects are referred
> to as parameters to the adaptors, functions, and utilities of the library
> ?
>

I don't understand what you are asking. It means that the function is
written
like this in the documentation:

template<class IntegralConstant>
constexpr auto if_(IntegralConstant);

But its actually a function object like this in the code:

struct if_f
{
    template<class IntegralConstant>
    constexpr auto operator()(IntegralConstant) const;
};
const constexpr if_f if_ = {};

However, `if_c` is written like this in the documentation:

template<bool B, class F>
constexpr auto if_c(F);

It requires the bool `B` template parameter explicity. So in the code it is
written as a function and not as a function object.
 

>
> The rest of the general About section is fairly straightforward. I still
> have no idea of the general functional of the library and why I should
> use it. I will only gain an idea of what the library does by reading the
> specifics of each adaptor, decorator, function, and utility. This seems
> to be the gist of the documentation to me. If I want to understand what
> the library does for me in working with function objects and lambda
> functions I have to read the specific documentation of each entity in
> the library and then go back to the Quick Start and More Examples
> sections to further understand how some of these entities are used.
>
> I think the library documentation would have been much better if there
> were a discussion of what the adaptors, decorators, functions, and
> utilities of the library were meant to do to enhance user programming
> rather than give examples here and there of usage and then leave it up
> to the end-user to figure out what, why, and how these entities are to
> be used. Quite frankly I don't have a use for a library that does not
> attempt to present itself as offering functionality that would be useful
> for me in the domain in which the library operates. if I have little or
> no idea of that domain I see no reason to think of using a library.
>
> Since Boost has a number of other libraries dealing with function
> objects, most notable the Boost Phoenix library, which is a sort of
> successor to the Boost Lambda library, I would think it would be
> advantage to the library author to stress functionality in the Fit
> library which goes beyond, improves on, or is different from the
> functionality in Boost Phoenix, in order to 'sell' end-users on the use
> of the Fit library in their code. I do realize that the Fit library
> deals with C++11/C++14 idioms, which means that it may be difficult for
> many end-users to understand, but I don't think it presents its
> documentation in such a way that makes its functionality easier to
> understand and I think it should do so. This does not mean that I will
> vote right now for Fit to be accepted or not accepted as a Boost
> library. I have to look much more carefully at the individual
> functionality of the adaptors, decorators, functions, and utilities of
> the library to understand what it actually does, before I can vote one
> way or another. But I hope my comments and questions about the
> documentation to the library will aid the library author in improving
> the documentation for end users like me, who are very interested in
> library enhancements to function object/lambda function functionality,
> but who find the documentation difficult and limiting in certain ways.
>

Thanks for your feedback, and it will be very helpful in improving the
documentation.



Boost-users list run by williamkempf at hotmail.com, kalb at libertysoft.com, bjorn.karlsson at readsoft.com, gregod at cs.rpi.edu, wekempf at cox.net