Re: [boost] Re: [function types] Formal Review begins today.

From: Jody Hagins (jody-boost-011304_at_[hidden])
Date: 2005-06-07 01:04:46

On Mon, 06 Jun 2005 22:37:06 +0200
Tobias Schwinger <tschwinger_at_[hidden]> wrote:

> OK. All I have to say for my excuse is that English is only my
> secondary  language...

Well, about the closest I can come to a secondary language is C++
(though I took a few years of Latin ages and ages ago).

> It means that (given the your compiler is supported by the library)
> all that can  be done with Boost.TypeTraits' function_traits class
> (and more) can also be done  with the FunctionTypes library.

That is a much better description.

> > After reading the OVERVIEW and MOTIVATION, I am still at a loss for
> > what benefit this library will provide.  I can make some reasonable
> > assumptions, but I would think that I should have a much better
> > picture than I currently have from reading those two sections.
> 
> What exactly is unclear ?

Well, please understand that when I read stuff as a "reviewer" I do so
in a state of ignorance (some may say I live ther, but that is another
story).  I do not think the overview and motivation sufficiently
describe the problems that the library is trying to solve.  I think too
many assumptions about the reader's expertise are made.  The library
itself is relatively easy to use, and does not require a lot of
experience.  However, I think the descriptions are not sufficient to
show readers why they should use the library, and what problems it
solves.

> Here's a fundamental misunderstanding:
> 
> 
> There are no sets of types that can be _built_.
> 
> You just _name_ a set of possible kinds of function types to test
> against by  specifying a tag:
> 
>     is_function_type< function_pointer, T >
> 
> Tells me if T is contained in the set of "all function pointers",
> which is  described by the tag type function_pointer.
> 
> I can ask for a superset (all types handled by the library) like this:
> 
>     is_function_type< any_function, T >
> 
> Or a subset:
> 
>     is_function_type< variadic_function_pointer, T >
> 
> 
> Did you read the Tags section at all ? Was it unclear ? Where ?

Yes, I read it, and I understand it.  However, the documentation is a
bit unclear, as it implies a set of types, not one specific tag
identifier.  I'm not trying to be difficult, but I am trying to find
places that need improvement.  In this case, "if a given type is element
of a set" along with the description of Tag, where any of the tag types
are allowed, can cause confusion because a set implies one or more
items.  I would suggest changing the documentation from using the term
"set" to being more explicit about using one of the tag types.

Again, however, this is just the opinion of one person.  Take it for
what it's worth.

> > For the function calls, the descriptions make some assumptions
> > (like, it must be called with a function type).  Are these
> > suggestions for good style, or will the implementation provide a
> > compile-time assertion, or will you ger undefined behavior if you
> > violate the assumption?
> >
> 
> If you violate the preconditions the behaviour is generally undefined.

Hmmm.  I would prefer a compile time assertion inside the functions, if
possible.

> However, the type members won't be defined to allow better diagnostics
> for  client code (this is currently undocumented).

I do not understand the above sentence.

> > It would also be helpful to be a bit more explicit about the
> > difference between function_type_parameter and
> > function_type_parameter_c, since not everyone groks MPL as second
> > nature.
> 
> Well, in case you don't know MPL (although the primary audience most
> likely  will) you can still have a look at the synopsis and look for
> the version with  non-type template parameter...

I would disagree with you here.  Many boost users do not know MPL.  Many
more probably have a cursory knowledge of MPL, but still need
documentation handy to make use of it.

> > How do functors fit in here?  If a class overloads operator(), is it
> > considered a function type?
> 
> 
> No. Is the definition really that unclear ?
> 
> How could this probably work if operator() is a function template ?
> 
> You can decompose a member function pointer to a parentheses operator
> (which  implies it's already instantiated if it's a template
> function), though (after  deduction or using some kind of typeof
> operator).

No, it is clear, but I would think that some notes about operator(),
boost::function, and boost::lambda would be appropriate, since some
folks may want to use them in some ways related to function_types.

> > knowledge of the MPL.  However, the docs seem to take too much for
> > granted, and make too many assumptions.  I'd like to see more
> > detail, especially in the descriptions.
> 
> What do you mean with "assumption" ? Preconditions on template
> arguments ?

I think interface documentation should make the lowest common
assumptions.  Not everyone is familiar with the types of problems this
library is trying to solve.  I am sure you are not merely targeting an
audience of people who could implement this library themselves, but
those who would like this functionality without implementing the
details.

FWIW, most boost libraries fail in this regard, in my opinion.  Library
documentation should make as few assumptions about the knowledge and
experience of the user as possible.

> As this library's classes are _slightly_ more complex in it's use than
> the ones  of Boost.TypeTraits (in some light it can be seen as an
> extension) what makes  you think there has to be so much more detail ?

Because the current detail is not sufficient ;-)  Seriously, I think
this library is very much in the reach of a boost newbie to use. 
However, the documentation and examples are written for a more
experienced audience.  Thus, I do not think the documentation fits a
significant segment of potential users.  If you do not intend to target
relatively new users to boost, then I guess you can leave it alone.

> 
> > After my initial reading, I am still not entirely sure about
> > function_type_signature.  I would like to see more description
> > information.  Also, I do not like the "types" member.  What is the
> > rationale for the ordering of the types (return, [class],
> > parameters)?  Callers would have to query even more information to
> > determine how to interpret types.
> 
> These members are documented at all because they might be helpful in
> some rather  rare cases - I should probably remove some of them from
> the documentation.

I like them there, but they do introduce questions about usage.  In
particular, you need to leave "kind" because as far as I see, it is the
only way to get the tag identity of a signature.

I question the "types" because I think it could be a little easier to
get the return type, and the parameters without the optional class
sandwiched inbetween.

> BCC is broken for all sorts of reasons. It is _not_ supported and does
> _not_  speak enough ISO-C++. Btw. I know a workaround for the problem
> regarding  function references but the lack of partial specialization
> for member function  pointers is much worse.

Fine with me.  I've been advocating dropping compilers that are too
broken, or require too many workarounds, for a while now.  However, BCB
is used by a number of boosters, and until Borland comes out with
something else, they are a bit stuck.  Maybe an explicit note about BCB
would be a good addition to that section.

> > Should the CONFIGURATION section go before the detailed descriptions
> > of the function calls?
> > 
> 
> Should it ?

Dunno.  I had questions about the calling convention and arity long
before I got to the section called CONFIGURATION.  It was not obvious at
all when I looked at the table of contents to the left that I should go
to the CONFIGURATION section to answer those questions.

> > In general, I do not like using test assertions as examples.  I know
> > lots of boost stuff uses this methodology, but it does not provide
> > much information.  If tests are used, then they should include LOTS
> > of documentation describing exactly what is (and is not) happening,
> > and sufficient justifications.
> 
> I never had problems with "assertions as examples" as a user...

Good for you.  I doubt that is the case for everyone.  Most of these
tests are unit tests, which do not necessarily show typical use cases. 
In my opinion, I'd like to see typical real-life use cases as examples. 
In particular, something that solves the main reasons for the library
existence, so I can see true ways of using the library.

> How about a callback registration that knows from the signature of the
> 
> registered function the data to call it with ?
> 
> (This was my reason to need the functionality of this library)

This seems like a reasonable example, and will probably use most of the
interface as well.

> How could someone unfamiliar with template metaprogramming (with or
> without  using MPL) possibly be interested in using this library ?

How could someone unfamiliar with socket programming possibly be
interested in a socket library?  How could someone unfamiliar with
signals/slots possibly be interested in the signals library?  I use a
number of boost libs on a daily basis.  However, I did not start using
them because I was already an expert in that domain.  Primarily, I
started looking at some documentation, and it then hit me how I could
use the lib to solve some of my own problems (or later, when a problem
came up, I rememebered something I read about a lib). 

I think you are approaching the documentation from the standpoint of
someone who already knows the details of implementing and using the
library, and not from the POV of someone who does not even know if they
should use the library.  I think we should strive to meet users where
they are, and through documentation, bring them to the level of the
developer.

> So I'm not sure you are among the intended audience. And I really
> would love to  hear more voices from those who undoubtfully are, on
> what _exactly_ needs to be  improved.

Don't be so sure ;->  I'm not exactly the novice for which you seem to
take me.  However, I do believe that documentation should be written in
that vein (and I also believe documentation should be reviewed in the
same vein).

If you still think I've not given enough exact information, then I
apologize, and hope that someone else can make it more clear.  Also,
please do not fall into the trap that some other submitters have fallen
into: reviews are not attacks on people, but ideas.

> > Finally, I'd like to see some examples that support the motivation. 
> > The author cites some reasons for the library to exist.  I want
> > proof, in the form of examples that show how difficult (or
> > impossible) it is to do what he wants without the library, and then
> > examples showing how the
> 
> E.g. let's extract the first parameter of a member function pointer
> type:
> 
> Currently there is no way to do it except use Boost.Preprocessor to
> create a  cascade of partial template specializations for every
> possible arity both with  and without ellipsis for every calling
> convention required (or write it by hand,  if you like ;-) ).
> 
> > same problem is easily solved with the library.  I do not think this
> > is just unique to this library.  I think it is important for all
> > libs, hint... hint...
> 
> With the FunctionTypes library the above scenario looks like this:
> 
>      function_type_parameter_c<T,2>::type
> 
> and it will compile as fast as the hand written version (the library
> provides  preprocessed headers - and is probably even faster because
> plain function types  and function references are transformed to
> pointers before using specialization  to match the type).

Actually, this is a great example, but note that it will bring up more
questions (e.g., why 2 and not 1?  and how would I do it if I did not
know it was a member-function-ptr type?  -- which is the basis for my
question about "types" since it requires some knowledge about the
optional class element of the sequence).

I'm really looking forward to the callback registration example.  I
think it is similar to something I wrote to help automate registration
of slots with the appropriate signals (though probably more general).

> Thank you for the huge ammount of feedback !

You bet.  I only hope some of it turns out to be valueable, and not just
"reply-fodder."

Thanks again for your submission, and desire to enhance open source
libraries.