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

From: Brian Braatz (brianb_at_[hidden])
Date: 2005-06-07 10:30:14

> -----Original Message-----
> From: boost-bounces_at_[hidden]
[mailto:boost-bounces_at_[hidden]]
> On Behalf Of Jody Hagins
> > 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.
> 
[Brian Braatz Writes:] 
THANK YOU JODY- 

I was going to say that (grin).

Allow me to add a suggestion. PICK YOUR TARGET person's skills. And then
write your docs to that person.

I would advocate - if you can pull it off- think about someone you know
who has 2-3 years CPP experience. Think about how you would communicate
your library to that person.

Walk them through using the library and solving problems with the
library. Assume the user knows VERY LITTLE about metaprogramming etc.

Hope that helps, and thank you Jody for spending the time to write up
your feedback :)