[boost] Re: [Review] Named parameters library

From: Pavel Vozenilek (pavel_vozenilek_at_[hidden])
Date: 2004-11-13 11:31:41

"David Abrahams" wrote:

 _____________________________________________________
> > 1. Headers should contain
> >
> > #if (defined _MSC_VER) && (_MSC_VER >= 1200)
> > #  pragma hdrstop
> > #endif
> >
> > It has effect on VC and Intel C++ users.
>
> What effect does it have?
>
(slight) decrease of compilation time.

(Like http://aspn.activestate.com/ASPN/Mail/Message/boost/1798707)

 _____________________________________________________
> > 6. could the code snippets be visually separated
> >    from the rest, e.g being in boxes and color syntax
> >    highlighted?
>
> They are already in gray boxes.  As for color syntax highlighting,
> that's not easy for us to do unless we convert the documentation
> source format... which is a possibility.
>
(There's easy to use Win32 tool written by Joaqin M Lopez Munoz
that does syntax highlighting of small snippets,
e.g. as in multi_index container docs.)

 _____________________________________________________
> > 8. What I miss in documentation:
> >
> >  - Information about overhead:
> >       - numbers/graphs for at least two compilers
> >       - estimate how the overhead changes with
> >         # of parameters and their type
>
> Are you curious about compile time or runtime?
>
Runtime (plus whether it has noticeable impact
on compilation time for this or that compiler).

> >  - What happen when I change foo_impl() signature?
> >    Will it quietly compile
>
> I am not convinced this belongs in the documentation, unless we are
> going to change our documentation standards drastically.  Few other
> libraries discuss the quality of error message you get when they are
> misused.
>
Info whether change in foo_impl signature causes
compiler error (as if no named_params are used)
could be there.

> >  - Info whether there are any additional constructors
> >    or assignements called for object as parameters.
>
> ??
>
I mean info whether there's overhead when passing objects
through this library.

> >  - Info about exception safety.
>
> What, specifically, are you curious about?  There's nothing much to
> say; all the library does is introduce a forwarding layer.
>
That.

> >  - Whether it is possible to have both "named params"
> >    function foo() and the original signature function
> >    "foo" and whether there could be any problems.
> >    Can the original signature foo() be externs "C"?
>
> I'm confused by the question.  Except for the need to write ref(), the
> "named params" function foo supports the original calling signature.
> I concede that if you have questions the docs need to be beefed up,
> regardless of the questions' validity.
>
I mean I have function:
extern "C" BOOL WINAPI CreateProcess(....many many parameters...);

Can I have it and named_params enhanced version
in the same TU?

> >  - Do overloads of "named params" functions work?
> >    Example if they do.
>
> Yes, that's the whole point of section 4, "Controlling Overload
> Resolution."  Can you help me understand why that wasn't clear from
> the text?
>
Bad understanding on my side.

> >  - I would welocme detailed table what features do
> >    not work with this or that compiler (more than the
> >    single line of text now).
>
> On the compilers we tested, all the detail is given by the simple list
> in the doc.  Would it really help to draw boxes around those lines?
>
Yes, boxes help quite a lot.

> >  - Would it work to provide "named params"
> >    overload of existing C functions?
> >    E.g. Win32 API functions?
>
> Again, that overloading works is the point of section 4.  Yes.
>
Was redundant question of me.
I think there should be example for a Win32 function.
Its very useful feature.

> >  - What does need to be in header and what can be
> >    put in implementation file? Example(s).
>
> Everything goes in the header.  You could use extern declarations for
> the keyword objects and stick them in an implementation file instead
> of putting them in an unnammed namespace, but it will be more
> inconvenient.  Again, this is just standard C++; why is there any
> mystery here?
>
While inconvenient it could be done (because of compilation
times).

My question was more asking for example
so reader will register and remember this possibility.

> >  - Is there way to make definition of pImpled
> >    member functions easier?
>
> Specifics, please?
>
Was answered bellow.

> >  - Iteration over parameters is undocumented.
>
> Why should we document iteration over parameters?  Maybe I don't
> understand what you have in mind.
>
It may be useful for debugging purposes
(but it may be hidden by helper function or macro).

> >  - There should be info whether the library headers
> >    can be part of precompiled headers (= has any
> >    compiler problems?)
>
> It's standard C++, and subject to the same problems that any other
> library might have with certain precompiled header implementations, if
> any such problems exist.  I don't use PCHs, so lack the expertise to
> find the specific information, but would be happy to include it in the
> docs if someone else supplies it.
>
It was question whether any supported compiler
complains now. BCB is known for having insiduous
bugs here and solving them makes hair gray.
Any info on potential problem helps.

> No offense intended, and I really appreciate your interest in the
> library, but this seems typical of your questions.  The docs
> shouldn't be expected to answer every vague question that pops into
> your head.
>
I guess the library would be mostly used to make already written
interfaces easier to use. Ending project phases and maintenance
are under time pressure and if the docs is detailed it makes
changes less stressful.

> >    All possibilities asked in [8] should be covered.
>
> I disagree.
>
These test may uncover problems with (old) compilers.

 _____________________________________________________
> > 13. debugging support: could there be simple function/macro
> >       which iterates over all named parameters and puts them
> >       (in readable, pretty form) into single string?
> >      Such string can then be printed, shown in IDE tooltip
> >      for examination etc.
>
> Details, please?
>
My thought was having
string s = extract_all_parameters_info_readable_form(...);
and then being able to see the values in "s" easily.

But it would require formatting or serialization support
to be complete. Too much work
not worth of the effort, likely.

/Pavel