Re: [boost] [parameter] Tutorial checked in

From: David Abrahams (dave_at_[hidden])
Date: 2005-07-18 21:47:16

Angus Leeming <angus.leeming_at_[hidden]> writes:

> David Abrahams wrote:
>> I think the tutorial documentation is close to complete.  Last minute
>> editorial comments would be appreciated.  See
>>    libs/parameter/doc/html/index.html
>
> Dave, I have a question about documentation of *my* library that uses
> Boost.Parameter.
>
> Documentation of the original new_window example is straghtforward because
> the public interface is exactly what the user sees and uses:
>
> window* new_window(
>    char const* name, 
>    int border_width = default_border_width,
>    bool movable = true,
>    bool initially_visible = true
>    );
>
> However, the interface to the equivalent function that uses Boost.Parameter
> is extremely complex, even if the resulting usage is beautifully simple:
>
> window* w = new_window("alert box", movable=false); // OK!
>
> So, my question. How would you go about documenting this
> Boost.Parameter-ized interface? 

Good question.

> I guess I'm suffering from a lack of imagination, but I'm genuinely
> stumped by this. Perhaps you could add such a documentation to the
> dfs example?

Heh, well, not until we settle on a way to write it.  Off the top of
my head, I don't know how you'd do it.  Maybe you'd show the
"non-enabled" public interface as above for new_window, and establish
a concept, "named parameter function object," that describes how such
a non-enabled "idealized" public interface maps onto an actual enabled
interface.  The concept would have to establish conventions for things
like whether non-templated function arguments are matched with is_same
or is_convertible, for example.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com