<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>&gt; Dear Boost community, sorry for the late anounce
<br>&gt;
<br>&gt; The formal review of Paul Fultz II&#39;s Fit library starts today, 2nd March
<br>&gt; and ends on 13th March.
<br>&gt;
<br>&gt; Fit is a header-only C++11/C++14 library that provides utilities for
<br>&gt; 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 &quot;provides utilities for functions and 
<br>function objects.&quot; 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 &#39;function&#39; 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 &quot;function&quot; 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 &#39;functions&#39;. 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>&quot;We can make it behave like a regular function if we construct the class 
<br>as a global variable.&quot;
<br>
<br>What about a non-global
<br>
<br>sum_f sum = sum_f();
<br>
<br>makes &#39;sum&#39; not behave like a regular function other than the fact that 
<br>the variable &#39;sum&#39; 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 &#39;We can also make this print function varidiac, 
<br>so it prints every argument passed into it.&#39; means ?
<br></blockquote><div><br>I&#39;ll try to explain that better, but basically it will print each argument, so:<br><br>print(&quot;hello&quot;, 5); // Will print &quot;hello&quot; 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 &#39;Quick Start&#39; 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&#39;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&#39;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>&#39;Definitions&#39; and &quot;Documentation Syntax&#39;. 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 &#39;Functions&#39; and &#39;Utilities&#39; 
<br>are not &quot;defined&quot; in this Overview I am left to wonder if &#39;Functions&#39; 
<br>and &#39;Utilities&#39; 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 &quot;Definitions&quot;.<br> </div><blockquote class="gmail_quote" style="margin: 0;margin-left: 0.8ex;border-left: 1px #ccc solid;padding-left: 1ex;">
<br>In the &#39;Signatures&#39; section of the Overview I read:
<br>
<br>&quot;All the functions are global function objects except where an explicit 
<br>template parameter is required.&quot; I honestly don&#39;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&#39;t understand what you are asking. It means that the function is written<br>like this in the documentation:<br><br>template&lt;class IntegralConstant&gt;<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&lt;class IntegralConstant&gt;<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&lt;bool B, class F&gt;<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&#39;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 &#39;sell&#39; 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&#39;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>