[boost] Re: [Review] Named parameters library

From: David Abrahams (dave_at_[hidden])
Date: 2004-11-13 17:44:57

"Pavel Vozenilek" <pavel_vozenilek_at_[hidden]> writes:

> "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.

Are you serious?  I can just drop that indiscriminately in every
header I write and my compilation times will go down?  Why doesn't the
compiler just do that for me?

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

?? That message talks about a different pragma.

>  _____________________________________________________
>> > 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.)

The documentation is generated, not hand-written, so it would be
nontirivial to inject that tool into the build chain.

>  _____________________________________________________
>> > 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).

Hm.  The params object just stores references to the outer parameters.
There shouldn't be much overhead beyond, possibly, the cost of copying
pointers to the actual arguments into the params object.

>> >  - 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.

I still don't understand that question.  There's no mystery here:
foo_impl is defined thus:

  template<class Params>
  void foo_impl(const Params& params)
  {
      std::cout
          << params[name | "unnamed"] << " = "
          << params[value | 0] << "\n";
  }

and it is invoked directly by the forwarding functions.  Everything
except the exact type of the Params object that gets passed is
completely exposed, so if you know C++ you ought to be able to draw
your own conclusions.

>> >  - 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.

Okay.

> 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?

Yes, of course.  They're just ordinary function templates, as you can
plainly see from the documentation.

>> >  - 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.

How?  It's really hard for me to believe that.

>> >  - 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.

It's not a feature of this library.  What you're asking is the same as
asking whether I can write any other function template and overload it
with a Win32 function.  There's no magic here.

>> >  - 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.

Documentation that gives too much information is hard to use,
especially if it is not particularly relevant to the library.  I think
the documentation could be improved, but if we added everything you're
asking for I'm sure it would be even less clear than it currently is.

>> >  - 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).

I don't understand what you have in mind.  What kind of iteration?

>> >  - 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.

It makes no sense to me to add documentation about compiler problems
that are just as likely to interact with some other library as with
this one.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com