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 <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

...

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

Hello Joaquín, Thank you for explaining the documentation. I appreciate your hard work and dedication to the docs. I do think that it is unusual for an open source project to have such emphasis placed on its documentation. In the spirit of getting feedback out there, please allow me to challenge a few things. I don't mean this as criticism of you personally or any other boost contributors; I'm just trying to help. The tutorial and examples provided for multi_index are good. That is where I started and I was able to learn a lot from them. I totally agree with your learning English/dictionary analogy. It was when I tried to go beyond the material covered in the tutorial and examples that I started getting frustrated. That's when I went looking for a reference and that is what led to my first post. A reference that was more easily browsable by class and method like JavaDoc, the Asio libraries, Doxygen and MSDN would be extremely helpful. As it is today, one must do a lot of clicking and scrolling to get to a particular method description with its paramaters and return value. Patterning the multi_index reference documentation on the C++ standard docs certainly has some good logic behind it, but who looks something up in the C++ standard when they need to figure something out about C++? My guess is that it is not the typical C++ user. Everyone that I know refers to other reference materials. The C++ standard is certainly important if someone is trying to write a C++ compiler or a new implementation of the STL. So to me it seems like the C++ standard docs are most helpful to someone who is trying to *follow* or *implement* the standard, not *use* the standard. It seems like the boost library reference documentation is used mostly by people who are trying to *use* the library since the implementation is already done -- it's the header files themselves. From a user perspective, it seems like the documentation is patterned on an example that is suboptimal. In short, I think that a reference that was searchable and browsable by class name, type name, method name, etc would be much quicker and easier to use for the typical multi_index user. Thanks, Nick On Fri, Oct 10, 2008 at 1:10 AM, <joaquin@tid.es> wrote:

Hello Nick,

First of all, thank you for trying Boost.MultiIndex despite your struggle with the documentation. My opinions on the issues you raise are below.

Nick Martin escribió:

...

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.

The reference layout mimics that of the C++ standard, which is admittedly not the user-friendliest around, but has the virtues of being very precise, oriented towards concept description rather than member function description and, well, standard. It takes time getting used to, but once you know how to use it you can rest assured all the information you need is in there and is not particulary hard to find.

For a feel of how the C++ standard documentation looks like you can take a look at

http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2691.pdf

and, in particular, to chapter 23 (containers). The reference is organized according to the following scheme:

* General concepts and associated requirements (valid expressions, complexity, exception-safety, etc.) + Concept refinements (for instance, associative container is a refinement of container): valid expressions, complexity, etc. * Header synopsis: Lists, in pseudo-source-code form, the particular components provided by the header. For each such component: + Component description: Concepts modelled and particularities. + Component synopsis: lists in pseudo-source-code form the member functions, types, etc. associated to the component. + Description of those member functions or aspects that are not implicitly covered by the concepts modelled by the component. This point is important: for instance, you can see in the description of std::list that std::list::begin() and std::list::end() are not explicitly commented, because all that can be said about them is already covered by the description of the concept "container". Member descriptions are grouped (for containers at least) as follows: - member typedefs - constructors, copy and assignment - iterators - capacity - modifiers (memfuns changing the state of the class) - observers (memfuns not changing ths state of the class) - specific operations (ops not covered by the general concepts) - specialized algorithms (operator==, swap, etc.) The description of each member function covers the following aspects: - Argument requirements - Effects (side effects, changes in the state of the class) - Complexity - Exception safety If some aspect is not explicitly covered, some default is assumed: for instance, is no explicit exception safety guarantee is given, basic safety is assumed.

Another thing you might find interesting to bear in mind is that the reference, at least in the form provided by Boost.MultiIndex, is *not* the primary source to learn what the lib is about or how its general usage is: this is accomplished by the tutorial. The reference is meant to be used for finding *exact* information about the components provided, once you have a general feel for the library. To draw an analogy, tutorial and reference play the same roles as an english textbook and a dictionary do in the context of language teaching: you don't learn to speak English by diving head-first into the Merriam-Webster.

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_ind... 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.ht... .

The description of what a hased index is is given here

http://www.boost.org/doc/libs/1_36_0/libs/multi_index/doc/reference/hash_ind...

which follows the general outline described above: component description, after header synopses.

The main reference page is merely a directory to other sections, each devoted to a different concept and/or component.

* Header file "synopsis" - it is probably lost on me, but why are

...

excerpts of the source code included?

Hopefully explained above.

* 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?

Hopefully explained above: this pseudo-source-code is a terse way to list all the relevant pieces (types, member functions, specialized functions) provided by the component being documented.

* 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.

Oh. Well, the clauses "Effects", etc. are within a <blockquote> tag and should have an indentation making them easy to distinguish from "Modifiers" etc, which are section headers and appear without indentation. Do you see otherwise in your browser?

* 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.

Once you understand the general layout, it is not hard to locate what you want. For instance, if I want to consult the constructors of multi_index_container, I know I have to find them within the description of this class, under the section "constructors, copy and assignment". In fact, the contents of multi_index_container reference provides fast access to that section:

http://www.boost.org/libs/multi_index/doc/reference/multi_index_container.ht...

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).

Well, Boost.Bimap is designed on top of Boost.MultiIndex, and the docs from the latter heavy influence the former.

Besides, other Boost libs follow this same convention. Take a look at the following examples:

http://www.boost.org/doc/html/array/reference.html http://www.boost.org/doc/html/any/reference.html http://www.boost.org/doc/html/function/reference.html

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.

The ones that you mention are certainly superb libraries and I don't want to contend about whose docs are better. But I certainly think that the C++ std style is very well suited to a form of documentation that is not so easily attainable with Oxiygen and other annotation tools: the latter tend to focus on documenting each member function in isolation and favor the repetition of descriptions, while the C++ std way focus heavily on concepts: in fact, one can say that concepts are the primary part of a reference, and only departures from / extensions of the concepts are explicitly annotated.

I also think that the more you get acquainted with this style of reference documentation the better you'll like it.

I can see from the boost-users archive that documentation standardization

...

has been an issue for a while (goes back to at least 2005).

Unfortunately, I don't think an agreement about documentation style (as in exposition style, not visual layout) has been achieved. The only guide we got in this respect are the minimal indications given at:

http://www.boost.org/development/requirements.html#Documentation

I also realize that this is free software and the documentation is what it

...

is.

I know there's a feeling that open source is generally lacking in the area of documentation, but in this particular case I can assure you that documentation has been given prominent treatment right from the start. This might be open source software, but I've spent many hundreds of hours in it and my (unmodest) goal is that its quality be second to none (commercial sw included) in all aspects, including documentation. Matter of fact, more time has been invested in documentation than actual coding.

And I take all suggestions and criticisms very seriously. I'm not dismissing your complaints but trying to understand them better and, hopefully, address them in a satisfactory manner.

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.

Joaquín M López Muñoz Telefónica, Investigación y Desarrollo

_______________________________________________ Boost-users mailing list Boost-users@lists.boost.org http://lists.boost.org/mailman/listinfo.cgi/boost-users

Joaquin M Lopez Munoz wrote:

Nick Martin <nick <at> transdigita.com> writes:

...

The tutorial and examples provided for multi_index are good. That is where I started and I was able to learn a lot from them. I totally agree with your learning English/dictionary analogy.

It was when I tried to go beyond the material covered in the tutorial and examples that I started getting frustrated. That's when I went looking for a reference and that is what led to my first post. A reference that was more easily browsable by class and method like JavaDoc, the Asio libraries, Doxygen and MSDN would be extremely helpful. As it is today, one must do a lot of clicking and scrolling to get to a particular method description with its paramaters and return value.

My main objection against by-member documentation as typically produced with JavaDoc and other annotation tools is that they shift the focus from general concepts, which C++ happens to rely on more and more. Let me exemplify my point: consider the case where we are documenting an iterator class:

template<typename T> class my_container{ class iterator; ... };

Using the C++ std style, one can simply say:

"my_container<T>::iterator is a random-access iterator on elements of my_container<T>."

or something to that effect. Using by-member documentation, one can easily end up having something like:

iterator& operator++(); effects: blah blah return: *this; blah blah

void ++operator(int); blah blah

value_type& operator*() blah blah

[same for decrementing, random-access, addition, subtraction, etc.]

How's this more useful than simply stating that the iterator is random-access? Of course this is an extreme example, but hopefully you get my point: I think it's more useful, and ultimately easier for the reader as well, to rely on concepts as much as possible and avoid by-member repetitious annotations when a reference to a concept suffice. I admit there can be an entry barrier for those readers who expect an easily browsable list of members for each class, but in the end my hope is that the change of style to concept-based documentation pays off, as the iterator example hopefully shows.

Naturally good documentation involves both an overall look at how the classes/functions of a library work together and the specifics of each class/function in the reference part of the documentation. I see nothing wrong with shortening the reference portion of the documentation by referring to concepts, as long as the end-user can go from the concept to the generic functionality involved. This may be less often the case than you, as a Boost developer, think. In the example you give above it may not be obvious to the end-user what functionality a random-access iterator guarantees, but there is a good chance such a common concept can be found either in the end-user's current understanding, in the documentation for the C++ standard library in the C++ implementation which the end-user uses, or on the Interenet. For other 'concepts', which may be easily recognizable by Boost developers, because they deal with them every day, the end-user may be lost in determining what generic functionality that concept represents. So while I agree with you that concept-based explanations in the reference portion of a library may often be better than having to repeatedly notate what specific functionality is represented by a class, especially a template class, I would have you, and Boost developers in general, err on the cautious side in supposing that some concept terminology is easily understood by the end user.

Hi Nick, excuse my late answering Nick Martin escribió: [...]

As an example of my frustration with the docs - say I want to look at the ordered index's find method. With the docs, as is, starting from the reference section of the docs (http://www.boost.org/doc/libs/1_36_0/libs/multi_index/doc/reference/index.ht...) I do the following: 1. click on "ordered indices" 2. I either know that find is a "set operation" (not obvious to me) and click that link or I scroll down (page down key 12 times in my browser) until I find it (or search within the page for "find"). If I didn't know the name of the method, however, it would be quite time consuming and painful to browse until I found the "find" method 12 pages down. 3. As I mentioned in an earlier post the fonts are difficult to read. The method names themselves (seemingly the most important information on the page) is in a font that makes it hard to find. Other parts of the text are in bold or large fonts.

So basically the reference is only helpful if I already know the exact method name I am looking for. I think that this is a shortcoming that other documentation styles that I mentioned previously overcome quite nicely.

Today, there is no clickable set of method names at the top of the reference. I think that is a big problem.

Yes, I understand your point. Let me try to work something out. Would you think it a reasonable compromise to add for all those component member functions *with a description* a link from the member name at the component synopsis to the associated description? For instance, if we have // ordered indices template<...> class name is implementation defined { ... iterator begin(); ... std::pair<iterator,bool> insert(const value_type& x); ... } then begin would have no link (as there is no explicit description for this concept-covered memfun) but insert would be linked to the associated description down within the modifiers section. Would that suit you (to some extent at least)? I can do this without distrubing the general design of the reference.

I do not agree that the standard documentation is particularly aimed at implementers rather than users: in my opinion, the reference is a *contract* between the user and the implementer, and as such both parties have equal interest in understading it thoroughly.

I think that we may just have a fundamental disagreement here. It may be in a user's best interest to understand the standard thoroughly. Then again, it may not. Most people don't have the time, interest or need to understand the standard thoroughly. They write software that is compiled for them by a compiler. If they make a mistake the compiler tells them and they fix it. They don't need to read the standard in order for that to happen. In fact, it could be argued that for some, spending time reading the C++ standard is definitely not in their best interest. For instance, I don't need to know how my engine, antilock breaks, power steering, etc in my car works to be a perfectly safe, competent driver. I would argue that someone doesn't need to be thoroughly familiar with the details of the C++ standard to be a competent coder.

I don't think the analogy is correct: the standard (or any similar reference documentation) does not deal with the implementation (i.e. engine, breaks and so on) of the components, just with their external interface. The difference with other, more user friendly, documentation (like that in MSDN) lies in the method of exposition, not the information conveyed. One probably does not need to read the standard to be a good C++ programmer, but, in my opinion, the chances that some consult to the standard is eventually needed grow higher as one demands more of the language. [...]

I think a great example can be found in the MSDN STL documentation. I think that they strike a nice balance between concepts (your stated aim) and the ability to quickly navigate through the documentation and find information on a particular class, method, type, etc (what I feel is missing from the multi_index docs).

I don't think this documentation is so balanced, as it only mentions the relevant concepts in passing, much as a tutorial would do, without providing exact definitions for them. It entirely relies on by-member annotation. It could be made to have the best of woth worlds if the concepts were described in detail, which it does not seem to do. This documentation is great (and is superbly crafted) for quickly going to a given member function and finding out what it does, but it does nothing to emphasize the recurring themes across components: for instance, map::begin, set::begin, list::begin etc. all are annotated with almost identical descriptions (and even example code!) but nothing suggests that they are all equivalent in the sense that their behavior is dictated by the underlying container concept. Of course any reader will eventually realize this on her own, but I think it's more useful in the long run to stress these commonalities up front.

For instance the STL map class: http://msdn.microsoft.com/en-us/library/s44w4h2s.aspx From that high-level page I can click on the "map members" http://msdn.microsoft.com/en-us/library/xdayte4c.aspx and see at a glance all of the member typedefs, methods, operators, etc. From this page I can click on a member and get more detailed information. For instance, I can click on the "begin" method and see its return type, etc and even an example program showing it in use (http://msdn.microsoft.com/en-us/library/kweswzhx.aspx).

There are many other examples of documentation out there that do similar things.

I think that this style of documentation accomplishes what we both are seeking - easy to navigate by-member documentation that is focused on concepts.

Do you agree that this style of documentation would be an improvement over the current docs?

The ability to achieve such documentation standards is another question. I am sure it would take a lot of time and effort. I, for one, would really appreciate such an effort if it were to occur.

If you think the proposal I give above is something that would approach your documentation ideal, I can try to find some time to sketch something and show it here at the list (unless we find a volunteer to do it, of course :) ) Joaquín M López Muñoz Telefónica, Investigación y Desarrollo

Hi Joaquín, Sorry for taking so long to reply. Please see my comments below. Thanks, Nick Yes, I understand your point. Let me try to work something out. Would you

think it a reasonable compromise to add for all those component member functions *with a description* a link from the member name at the component synopsis to the associated description? For instance, if we have

// ordered indices template<...> class name is implementation defined { ... iterator begin(); ... std::pair<iterator,bool> insert(const value_type& x); ... }

then begin would have no link (as there is no explicit description for this concept-covered memfun) but insert would be linked to the associated description down within the modifiers section. Would that suit you (to some extent at least)? I can do this without distrubing the general design of the reference.

I'm not sure if I followed your example. I think that a link for every member method would be very helpful. If it is covered in the "concepts" section, a link to the concept would be fine. If it is not discussed in the concepts then a short description would be great.

I do not agree that the standard documentation is

...

particularly aimed at implementers rather than users: in my opinion, the reference is a *contract* between the user and the implementer, and as such both parties have equal interest in understading it thoroughly.

I think that we may just have a fundamental disagreement here. It may be in a user's best interest to understand the standard thoroughly. Then again, it may not. Most people don't have the time, interest or need to understand the standard thoroughly. They write software that is compiled for them by a compiler. If they make a mistake the compiler tells them and they fix it. They don't need to read the standard in order for that to happen. In fact, it could be argued that for some, spending time reading the C++ standard is definitely not in their best interest. For instance, I don't need to know how my engine, antilock breaks, power steering, etc in my car works to be a perfectly safe, competent driver. I would argue that someone doesn't need to be thoroughly familiar with the details of the C++ standard to be a competent coder.

I don't think the analogy is correct: the standard (or any similar reference documentation) does not deal with the implementation (i.e. engine, breaks and so on) of the components, just with their external interface. The difference with other, more user friendly, documentation (like that in MSDN) lies in the method of exposition, not the information conveyed.

One probably does not need to read the standard to be a good C++ programmer, but, in my opinion, the chances that some consult to the standard is eventually needed grow higher as one demands more of the language.

OK, fair enough.

[...]

...

I think a great example can be found in the MSDN STL documentation. I think that they strike a nice balance between concepts (your stated aim) and the ability to quickly navigate through the documentation and find information on a particular class, method, type, etc (what I feel is missing from the multi_index docs).

I don't think this documentation is so balanced, as it only mentions the relevant concepts in passing, much as a tutorial would do, without providing exact definitions for them. It entirely relies on by-member annotation. It could be made to have the best of woth worlds if the concepts were described in detail, which it does not seem to do.

I agree, it does not do a good job of explaining the concepts. They do have a "sample container" http://msdn.microsoft.com/en-us/library/tct9795e(VS.80).aspx where one can see explanations of methods like begin ( http://msdn.microsoft.com/en-us/library/72f9cxxe(VS.80).aspx). It is not apparent what this "sample container" is meant to convey by reading the description. I think that this sample container only really makes much sense after one already knows how the STL container classes already work.

This documentation is great (and is superbly crafted) for quickly going to a given member function and finding out what it does, but it does nothing to emphasize the recurring themes across components: for instance, map::begin, set::begin, list::begin etc. all are annotated with almost identical descriptions (and even example code!) but nothing suggests that they are all equivalent in the sense that their behavior is dictated by the underlying container concept. Of course any reader will eventually realize this on her own, but I think it's more useful in the long run to stress these commonalities up front.

The repetition does not bother me. I think that it is helpful to have every single member method explained in detail. If you wish to avoid repetition, you could have the link for something like the "begin" method go to its own page with the return type, etc explained, but then also have a link to the concepts page where the concept of the begin method is explained. In the MSDN documentation, the "sample container" section does emphasize that the behavior is dictated by the underlying container concept, but I think that it is confusing. Nowhere that I saw is it explained that this is a set of high level concepts that all of the container classes share.

For instance the STL map class:

...

http://msdn.microsoft.com/en-us/library/s44w4h2s.aspx From that high-level page I can click on the "map members" http://msdn.microsoft.com/en-us/library/xdayte4c.aspx and see at a glance all of the member typedefs, methods, operators, etc. From this page I can click on a member and get more detailed information. For instance, I can click on the "begin" method and see its return type, etc and even an example program showing it in use ( http://msdn.microsoft.com/en-us/library/kweswzhx.aspx).

There are many other examples of documentation out there that do similar things.

I think that this style of documentation accomplishes what we both are seeking - easy to navigate by-member documentation that is focused on concepts.

Do you agree that this style of documentation would be an improvement over the current docs?

The ability to achieve such documentation standards is another question. I am sure it would take a lot of time and effort. I, for one, would really appreciate such an effort if it were to occur.

If you think the proposal I give above is something that would approach your documentation ideal, I can try to find some time to sketch something and show it here at the list (unless we find a volunteer to do it, of course :) )

That would be great. My ideal: 1. Each class has an index with links to each member method 2. The member method has a description, each parameter is explained and the return type is explained. 3. The member methods have links to the concepts page that provide the conceptual overview, where applicable.

Joaquín M López Muñoz Telefónica, Investigación y Desarrollo _______________________________________________ Boost-users mailing list Boost-users@lists.boost.org http://lists.boost.org/mailman/listinfo.cgi/boost-users