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.