<div dir="ltr"><br><br>On Sunday, March 6, 2016 at 9:42:19 PM UTC-6, Edward Diener wrote:<blockquote class="gmail_quote" style="margin: 0;margin-left: 0.8ex;border-left: 1px #ccc solid;padding-left: 1ex;">On 3/3/2016 6:43 AM, Vicente J. Botet Escriba wrote: <br>> Dear Boost community, sorry for the late anounce <br>> <br>> The formal review of Paul Fultz II's Fit library starts today, 2nd March <br>> and ends on 13th March. <br>> <br>> Fit is a header-only C++11/C++14 library that provides utilities for <br>> functions and function objects. <br> <br>These are some comments/queries about the Fit documentation. <br> <br>Introduction <br> <br>The introduction says that Fit "provides utilities for functions and <br>function objects." But it seems as if Fit works only with lambda <br>functions and function objects. </blockquote><div><br>Fit works with any generalized Callable:<br><br>http://en.cppreference.com/w/cpp/concept/Callable<br> </div><blockquote class="gmail_quote" style="margin: 0;margin-left: 0.8ex;border-left: 1px #ccc solid;padding-left: 1ex;">The term 'function' normally encompasses <br>a much larger definition in C++ which includes global functions, static <br>functions, member functions, and lambda functions. </blockquote><div><br>Which is what Callable encompasses, but I used "function" since more <br>people are familiar with that than Callable.<br> </div><blockquote class="gmail_quote" style="margin: 0;margin-left: 0.8ex;border-left: 1px #ccc solid;padding-left: 1ex;">Fit needs to be more <br>precise in what it says it works with. It repeatedly refers to function <br>objects and lambda functions as 'functions'. I think this vagueness of <br>terminality is really confusing in the documentation. <br></blockquote><div><br>Perhaps, I should refer to the Callable concept early on then.<br> </div><blockquote class="gmail_quote" style="margin: 0;margin-left: 0.8ex;border-left: 1px #ccc solid;padding-left: 1ex;"> <br>Quick Start:Function Objects <br> <br>"We can make it behave like a regular function if we construct the class <br>as a global variable." <br> <br>What about a non-global <br> <br>sum_f sum = sum_f(); <br> <br>makes 'sum' not behave like a regular function other than the fact that <br>the variable 'sum' may eventually go out of scope ? <br></blockquote><div><br>In C++, a regular function is always global, there is no such thing as local<br>function(sans gcc extensions).<br> </div><blockquote class="gmail_quote" style="margin: 0;margin-left: 0.8ex;border-left: 1px #ccc solid;padding-left: 1ex;"> <br>Quick Start:Lambdas <br> <br>Why do we need both BOOST_FIT_STATIC_LAMBDA and <br>BOOST_FIT_STATIC_LAMBDA_<wbr>FUNCTION ? I would seem that <br>BOOST_FIT_STATIC_LAMBDA_<wbr>FUNCTION would be adequate and <br>BOOST_FIT_STATIC_LAMBDA is just redundant, mimicking lambda syntax to no <br>purpose. <br></blockquote><div><br>BOOST_FIT_STATIC_LAMBDA_FUNCTION and BOOST_FIT_STATIC_FUNCTION both define a<br>function at global scope, and can only be used at global scope, whereas<br>BOOST_FIT_STATIC_LAMBDA can be used to constexpr initialize local variables as<br>well. In fact, BOOST_FIT_LIFT uses this since it is not always clear what<br>context the user might call BOOST_FIT_LIFT.<br> </div><blockquote class="gmail_quote" style="margin: 0;margin-left: 0.8ex;border-left: 1px #ccc solid;padding-left: 1ex;"> <br>Quick Start:Overloading <br> <br>The overloading adaptors show two or more lambda functions. Can they <br>also work with function objects ? Or a mix of lambda functions and <br>function objects ? In fact all the reamining Quick Start topics show <br>examples with lambda functions. Do they also work with function objects ? <br></blockquote><div><br>Yes it can be used with function objects. I probably should show an example of<br>that as well. I used the lambdas because of the terseness of them.<br> </div><blockquote class="gmail_quote" style="margin: 0;margin-left: 0.8ex;border-left: 1px #ccc solid;padding-left: 1ex;"> <br>Quick Start:Variadic <br> <br>I do not understand what 'We can also make this print function varidiac, <br>so it prints every argument passed into it.' means ? <br></blockquote><div><br>I'll try to explain that better, but basically it will print each argument, so:<br><br>print("hello", 5); // Will print "hello" and 5<br> <br></div><blockquote class="gmail_quote" style="margin: 0;margin-left: 0.8ex;border-left: 1px #ccc solid;padding-left: 1ex;"> <br>I do not think the Quick Start explains very much since it is dealing <br>with adaptors of which we know almost nothing and the explanation for <br>these adaptors and what they actually do is very terse. </blockquote><div><br>Probably can expand the explanation of adaptors a little more. <br> </div><blockquote class="gmail_quote" style="margin: 0;margin-left: 0.8ex;border-left: 1px #ccc solid;padding-left: 1ex;">I realize that <br>is why it is called a 'Quick Start' is because it is just giving the <br>end-user a quick review of the sort of functionality that the library <br>entails, but I would much rather see a good Overview first before I look <br>at anything else in the documentation. <br> <br>More Examples <br> <br>The more examples section looks at useful cases for the library. Since I <br>haven't had an overview for the library yet it is disappointing that <br>this section comes before I really understand how the library is <br>organized with at least general functionality. I am now given a series <br>of some highly complicated library syntax without the least idea of why <br>any of this syntax should be as it is, what it means, or how it works. <br>That doesn't convince me to use the library at all. It just convinces me <br>that the library has some showy functionality which does clever things <br>for particular use cases which the library author wants to convince me I <br>am going to encounter in my own programming. <br></blockquote><div><br>Probably more explanation about each of the components used to build <br>the example will be helpful.<br> </div><blockquote class="gmail_quote" style="margin: 0;margin-left: 0.8ex;border-left: 1px #ccc solid;padding-left: 1ex;"> <br>Overview <br> <br>The overview section consists of explaining what a function adaptor, <br>static function adaptor, and decorator are. It also give me some notes <br>about the syntax of the documentation. I would call this section <br>'Definitions' and "Documentation Syntax'. One thing it is not is an <br>overview of the Fit library as far as I can understand what an overview <br>is. I also note that following large scale sections deal in Adaptors, <br>Decorators, Functions, and Utilities. Since 'Functions' and 'Utilities' <br>are not "defined" in this Overview I am left to wonder if 'Functions' <br>and 'Utilities' just mean anything in the library which is not an <br>adaptor or a decorator, and what distinguishes a function from a utility. <br></blockquote><div><br>This is a good point, the current overview should be called "Definitions".<br> </div><blockquote class="gmail_quote" style="margin: 0;margin-left: 0.8ex;border-left: 1px #ccc solid;padding-left: 1ex;"> <br>In the 'Signatures' section of the Overview I read: <br> <br>"All the functions are global function objects except where an explicit <br>template parameter is required." I honestly don't know what this is <br>supposed to mean. Does this refer to when function objects are referred <br>to as parameters to the adaptors, functions, and utilities of the library ? <br></blockquote><div><br>I don't understand what you are asking. It means that the function is written<br>like this in the documentation:<br><br>template<class IntegralConstant><br>constexpr auto if_(IntegralConstant);<br><br>But its actually a function object like this in the code:<br><br>struct if_f<br>{<br> template<class IntegralConstant><br> constexpr auto operator()(IntegralConstant) const;<br>};<br>const constexpr if_f if_ = {};<br><br>However, `if_c` is written like this in the documentation:<br><br>template<bool B, class F><br>constexpr auto if_c(F);<br><br>It requires the bool `B` template parameter explicity. So in the code it is<br>written as a function and not as a function object.<br> </div><blockquote class="gmail_quote" style="margin: 0;margin-left: 0.8ex;border-left: 1px #ccc solid;padding-left: 1ex;"> <br>The rest of the general About section is fairly straightforward. I still <br>have no idea of the general functional of the library and why I should <br>use it. I will only gain an idea of what the library does by reading the <br>specifics of each adaptor, decorator, function, and utility. This seems <br>to be the gist of the documentation to me. If I want to understand what <br>the library does for me in working with function objects and lambda <br>functions I have to read the specific documentation of each entity in <br>the library and then go back to the Quick Start and More Examples <br>sections to further understand how some of these entities are used. <br> <br>I think the library documentation would have been much better if there <br>were a discussion of what the adaptors, decorators, functions, and <br>utilities of the library were meant to do to enhance user programming <br>rather than give examples here and there of usage and then leave it up <br>to the end-user to figure out what, why, and how these entities are to <br>be used. Quite frankly I don't have a use for a library that does not <br>attempt to present itself as offering functionality that would be useful <br>for me in the domain in which the library operates. if I have little or <br>no idea of that domain I see no reason to think of using a library. <br> <br>Since Boost has a number of other libraries dealing with function <br>objects, most notable the Boost Phoenix library, which is a sort of <br>successor to the Boost Lambda library, I would think it would be <br>advantage to the library author to stress functionality in the Fit <br>library which goes beyond, improves on, or is different from the <br>functionality in Boost Phoenix, in order to 'sell' end-users on the use <br>of the Fit library in their code. I do realize that the Fit library <br>deals with C++11/C++14 idioms, which means that it may be difficult for <br>many end-users to understand, but I don't think it presents its <br>documentation in such a way that makes its functionality easier to <br>understand and I think it should do so. This does not mean that I will <br>vote right now for Fit to be accepted or not accepted as a Boost <br>library. I have to look much more carefully at the individual <br>functionality of the adaptors, decorators, functions, and utilities of <br>the library to understand what it actually does, before I can vote one <br>way or another. But I hope my comments and questions about the <br>documentation to the library will aid the library author in improving <br>the documentation for end users like me, who are very interested in <br>library enhancements to function object/lambda function functionality, <br>but who find the documentation difficult and limiting in certain ways. <br></blockquote><div><br><br>Thanks for your feedback, and it will be very helpful in improving the <br>documentation.<br><br></div></div>