Re: [boost] [MultiIndex] interface comments

Subject: Re: [boost] [MultiIndex] interface comments
From: David Abrahams (dave_at_[hidden])
Date: 2008-11-02 08:41:06

on Sat Nov 01 2008, Joaquin M Lopez Munoz <joaquin-AT-tid.es> wrote:

> David Abrahams <dave <at> boostpro.com> writes:
>> 
>> Just reading through the docs for this very useful library and I had a
>> few notes:
>> 
>> 0. The term /typelist/ (italicized) is used in the tutorial without
>>    definition.  Do you mean an MPL type sequence, or something else?
>
> Yep, strictly speaking it is an MPL forward sequence, as stated in
> the reference. I wrote "typelist" instead of plain "list" lest
> anyone took the latter as somehow related to run-time lists
> (std::list etc.) But not explaning the term "typelist" in advance
> is even more confusing, as I realize rereading the paragrapah. So
> I guess I'll revert to unitalicized "list". Do you think this
> would be clearer for an entry-level reader?

That might be clearer, yeah, if you're not going to say that
indices<...> is an MPL sequence.  You could also link the word "list" to
the place in the reference where you give more detailed info on it.

>> 1. Seems like the tags functionality could take advantage of Boost.Parameter
>>    to provide a nicer interface and save some code.
>
> I don't see how... Would you care to elaborate?
>

instead of:

  employee_set::index<name>::type& name_index=es.get<name>();

you could have

  employee_set::index<tag::name>::type& name_index = es[name];

I guess it's not a huge win.

> <shameless plug>For a very extensive and, IMHO, effective use case
> of Boost.Parameter have a look at the free-order template parameter
> interface of the (soon to be included in Boost) Boost Flyweight
> Library (http://tinyurl.com/6xxdkm ).</shameless plug>

Nice, but especially since those parameters are optional I wouldn't try
to exhaustively list all the combinations; the doc gives the impression
that they all need to be passed.  If the point is to make it easy for
the reader, I suggest you not overwhelm her with code ;-) The
Boost.Python docs explain this stuff in a simple way that nobody *ever*
asks me about, and doesn't require me to enumerate all the argument
orders.
  
>> 2. The "shortcuts" save exactly 1 character.
> [...]
>>    Notice the column in which "it" appears in both versions.  IMO these
>>    interfaces should be deprecated (i.e. not documented, and eventually
>>    removed) as they provide no readability advantage, hurt learnability,
>>    and complicate usage.
>
> Yes, you're absolutely right. I don't recall why I included
> the iterator "shortcuts" in the first place, but they probably
> confuse more than hurt. I'll do as you propose and begin their
> deprecation process in Boost 1.38.

Thanks for keeping an open mind about that :-)

Cheers,

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com