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-21 13:37:16

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_at_[hidden]
> http://lists.boost.org/mailman/listinfo.cgi/boost-users
>