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

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.

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

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.

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.

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.