Re: [boost] Re: threads comments

From: Jeremy Siek (jsiek_at_[hidden])
Date: 2001-09-03 15:01:23

On Mon, 3 Sep 2001 williamkempf_at_[hidden] wrote:

willia> --- In boost_at_y..., Jeremy Siek <jsiek_at_c...> wrote:
willia> >
willia> > in condition.html:
willia> >
willia> >   Template parameter "Pr" should be replaced with "Predicate"
willia> >   and linked to the definition:
willia> >   http://www.sgi.com/tech/stl/Predicate.html
willia>
willia> Do we make external links like this in Boost documentation?  I'm
willia> willing to make the change, just want to make sure it's appropriate.

In Boost we try to keep external links to a minimum, but encourage use of
and links to components/concepts in the C++ standard. The SGI STL web site
is a good location to point to for concepts such as Predicate that are
used in the standard. Therefore Boost encourages this kind of external
linkage.

There are a few concepts that the SGI STL docs and the C++ std differ, so
I've created C++ std compliant defs in the libs/utility directory. Notably
the Assignable concept.

willia>
willia> > Move xlock.hpp to a detail/ directory, or document it and
willia> >   make it "public".
willia>
willia> Currently it is documented, but it's also in the detail namespace (I
willia> expected others to make use of the templates).  I guess I've left
willia> these types in limbo, partially a detail item and partially public
willia> concepts.  A decision has to be made as to which direction it should
willia> really go.
willia> > in scoped_lock.html (and the other lock docs too)
willia> >
willia> >   Header, just use mutex.hpp here, xlock.hpp is an implementation
willia> >     detail, right?
willia>
willia> We can't use just mutex.hpp, we'd have to use recursive_mutex.hpp as
willia> well.  However, the type isn't defined in either of these, but is
willia> defined in xlock.hpp.  Even if it's fully turned into a detail I
willia> don't think this should be changed here.

Yes, others will use the stuff in xlock.hpp, but the question is *who*
those others are. Are they your ordinary user? No, they are library
authors. Therefore I encourage the move of xlock.hpp to detail/. Think
about the student trying to learn Boost.Thread for the first time... the
teacher will have to keep answering questions like "what's this
scoped_lock class template for?" and his reply "Oh, just ignore that".

I encourage that the documentation of the stuff in xlock to be removed
from the main documentation. Perhaps you could add an "Implementation
notes" page that refers to it.

Cheers,
Jeremy

----------------------------------------------------------------------
 Jeremy Siek                          http://php.indiana.edu/~jsiek/
 Ph.D. Student, Indiana Univ. B'ton   email: jsiek_at_[hidden]
 C++ Booster (http://www.boost.org)   office phone: [phone]
----------------------------------------------------------------------