Re: [Boost-users] [boost] [Fit]Â formal review starts today

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.