Re: [Boost-users] [mutli_index] class reference available? / How to detect insertion failures

Subject: Re: [Boost-users] [mutli_index] class reference available? / How to detect insertion failures
From: Nick Martin (nick_at_[hidden])
Date: 2008-10-09 19:51:40

Adam,
Thank you for your quick reply. I had looked at the particular page that you
reference, but was confused by its contents.

I was confused by the reference documentation included with multi_index for
a few reasons.

My main points of confusion came from:

   - Reference pages have no introductory text -
   http://www.boost.org/doc/libs/1_36_0/libs/multi_index/doc/reference/hash_indices.htmldoesn't
say what a hash index is, what it is used for, etc. The main
   reference page is especially terse
   http://www.boost.org/doc/libs/1_36_0/libs/multi_index/doc/reference/index.html.

   - Header file "synopsis" - it is probably lost on me, but why are
   excerpts of the source code included?
   - Large amount of source code inclusion - as a user of the library I
   haven't found the inclusion of portions of the headers particularly helpful.
   I am sure that there is a good reason for them to be there, but why not just
   have a simple line or two stating that a particular header is required for
   certain situations?
   - Font usage - why are "Effects" "Returns" "Complexity" in the same size
   (or very similar size) font as "Modifiers"? It took my eye away from the
   actual method names, which is what I was looking for.
   - Why are the constructors, method names, etc so far down the page (six
   page downs on my computer)? It seems like that is the information that is
   most helpful/searched for.

Now that I understand what I am looking at a little bit better, it does look
like multi_index does follow the same outline as some other boost libraries
(like bimap).

That said, multi_index still looks like it has a way to go to catch up with
some other libraries (Asio and Tuple, for instance), which I find much
easier to use and understand.

I can see from the boost-users archive that documentation standardization
has been an issue for a while (goes back to at least 2005).

I also realize that this is free software and the documentation is what it
is. As a user that is used to documentation from other vendors and other
styles (JavaDoc, DoxyGen, MSDN library), this documentation is severely
lacking. That is a shame because I think that multi_index itself looks like
a great library that should be used by as many developers as possible.

Thanks,
Nick

On Thu, Oct 9, 2008 at 3:50 PM, Adam Merz <adammerz_at_[hidden]> wrote:

> Nick Martin writes:
> >
> > There doesn't appear to be comprehensive class reference documentation. I
> > only figured out how to do simple tasks like inserting new items into the
> > container by looking at the examples
> > (http://www.boost.org/doc/libs/1_36_0/libs/multi_index/example/basic.cpp
> ).
> >
> > My specific question (which the examples don't seem to cover) is how to
> tell
> > when insertion fails. What if the new item's unique key constraint fails?
> I
> > have had many other, seemingly simple questions that I would hope could
> be
> > answered in minutes or seconds that have turned into hours of trial and
> error
> > and combing through example programs. What other resources are out there
> that
> > I refer to in order to use this great library?
>
> Full reference documentation is here:
>
> http://www.boost.org/doc/libs/1_36_0/libs/multi_index/doc/reference/index.html
>
> Insert behavior is documented here:
>
> http://www.boost.org/doc/libs/1_36_0/libs/multi_index/doc/reference/ord_indices.html#modifiers
>
> In answer to your specific question, "The return value is a pair p.
> p.second is
> true if and only if insertion took place. On successful insertion, p.first
> points to the element inserted; otherwise, p.first points to an element
> that
> caused the insertion to be banned. Note that more than one element can be
> causing insertion not to be allowed."
>
> _______________________________________________
> Boost-users mailing list
> Boost-users_at_[hidden]
> http://lists.boost.org/mailman/listinfo.cgi/boost-users
>