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.