Boost logo

Boost :

Subject: Re: [boost] [Fit] formal review starts today
From: Edward Diener (eldiener_at_[hidden])
Date: 2016-03-06 22:41:42

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.


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. The term 'function' normally encompasses
a much larger definition in C++ which includes global functions, static
functions, member functions, and lambda functions. 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.

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 ?

Quick Start:Lambdas

Why do we need both BOOST_FIT_STATIC_LAMBDA and
BOOST_FIT_STATIC_LAMBDA is just redundant, mimicking lambda syntax to no

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 ?

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


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.

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 ?

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.

Boost list run by bdawes at, gregod at, cpdaniel at, john at