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: joaquin_at_[hidden]
Date: 2008-10-17 09:46:11

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