Re: [boost] Formal Review: Indexed Set

From: Rob Stewart (stewart_at_[hidden])
Date: 2004-03-30 13:18:42

From: =?iso-8859-1?Q?Joaqu=EDn=20M=AA=20L=F3pez=20Mu=F1oz?= <joaquin_at_[hidden]>
> Rob Stewart ha escrito:
> > From: =?iso-8859-1?Q?Joaqu=EDn=20M=AA=20L=F3pez=20Mu=F1oz?= <joaquin_at_[hidden]>
> > > Rob Stewart ha escrito:
> > >
> Yeah. Rephrased it, hope it reads better now:
> 
> "The Boost.IndexedSet library provides a class template named indexed_set
> which enables the construction of containers maintaining one or more indices
> with different sorting and access semantics. Indices provide interfaces similar to
> those of STL containers, making using them familiar."

That is better.

> > > > I have two questions.  First, why is this information buried in
> > > > the advanced topics page?  The mode should be highlighted in the
> > > > main documentation path.
> > >
> > > I thought the tutorial was hard enough as it was and decided to
> > > move all the non-essential stuff to a different page. Admittedly,
> > > other topics covered in this section are really much more advanced.
> >
> > The point is that this issue isn't "advanced."  It is part of
> > normal usage of the library.  Indeed, it is quite possibly of
> > more use to less advanced users.
> 
> I'll think of it. I don't feel comfortable with this section being in
> the tutorial, which is more about concepts than configuration.

I think the problem is you have two extremes: tutorial and
advanced.  A third category of documentation, normal, could
alleviate the problem.  Most of the documentation should be part
of the normal category, some of it -- simplified, glossing over
details -- goes in the tutorial, and some of it -- the stuff most
won't care to know or won't need except for certain circumstances
-- goes in the advanced section.

Thus, your tutorial section could be pared down, with some of the
existing content moved to the "normal" section.  Also, some of
the "advanced" content can move to the "normal" section.  Having
done that, the mode control fits nicely in the "normal" section.

What do you call the "normal" documentation?  I don't know.
Maybe the key is to have more, smaller sections referenced in the
TOC such that "Tutorial" and "Advanced Topics" are just two of
the entries.

> > > > I don't like the assymmetry between get<> and the pair
> > > > nth_indexed_type<> and indexed_type<>.  I'd prefer that
> > > > indexed_type<> be used, like get<>, for either a number or a tag.
> > >
> > > I'd prefer it also, but AFAIK it cannot be done. You just cannot
> > > "overload" a template to accept type and non-type arguments.
> >
> > I haven't looked at the code, but I'm confused.  How can one use
> > type and non-type arguments with get<> but not with the others?
> 
> get<> is a function template, index_type is a class template.
> Future revisions of the language may allow for class template
> overloading, if I'm not wrong.

Not only is that little detail obvious from the name (the
"_type") but looking back at the tutorial, it is clear that
indexed_type is a class template.  Furthermore, get is always
called, so it is obviously a function template.  All I can say
is, doh!  I'm sorry for the noise.

-- 
Rob Stewart                           stewart_at_[hidden]
Software Engineer                     http://www.sig.com
Susquehanna International Group, LLP  using std::disclaimer;