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.ht....
- 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
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
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
tell 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.ht...
Insert behavior is documented here:
http://www.boost.org/doc/libs/1_36_0/libs/multi_index/doc/reference/ord_indi...
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