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.html doesn'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@hotmail.com> 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@lists.boost.org
http://lists.boost.org/mailman/listinfo.cgi/boost-users