Re: [boost] [Fit]Â formal review starts today

Subject: Re: [boost] [Fit] formal review starts today
From: Edward Diener (eldiener_at_[hidden])
Date: 2016-03-07 03:51:27

On 3/7/2016 12:15 AM, Paul Fultz II wrote:
>
>
> 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

Please document this. A generalized Callable is a much bigger set of 
functionality than just lambda functions and function objects.

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

A 'function' and a Callable in C++ are two entirely different things. 
Use the one that is precise and don't worry what people are familiar 
with. Explain what a Callable is early on ( I know you explain it later 
) if you feel that people do not know what it means.

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

See above.

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

My point is that the non-global 'sum' in my example above behaves just 
as much like a regular function as your global 'sum'. You may want to 
promote the idea of global function objects but I think that this is 
personally a bad idea. IMO global variables of any kind are to be avoided.

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

It might be good to add that when the end-user first encounters 
BOOST_FIT_STATIC_LAMBDA, because the name does not suggest 
initialization of local objects. Furthermore I cannot imagine why one 
would want to use it to initialize a local object, so you might want to 
explain the benefit of doing so as opposed to the normal syntax for 
creating a lambda function.

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

Evidently the adaptors can be used with any Callable. I think you should 
make that point very strongly and show that in examples also.

>
>
>>
>> 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 wouldn't associate that with the word 'Variadic' but I do think you 
need to explain that more clearly.

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

Good idea. What do adaptors create ? Different function objects I would 
imagine ? In that case how about the explanation that adaptors take 
Callables as input and generate function object types that adapt the 
original functionality of one or more Callables to some other purpose.

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

I would suggest an Overview that discusses the main functionality of 
adaptors, decorators, functions, and utilities.

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

I don't understand to what you are referring when you say 'function'. 
Are you talking about adaptors in your library, functions in your 
library, or what ? Please try to understand that your use of the word 
'function' is very broad but that the word 'function' in C++ has a much 
narrower meaning.

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