2008-05-03 Hans Boehm <Hans.Boehm@hp.com>

	* doc/gcinterface.html: Improve C++ interface documentation.

2 files changed, 19 insertions, 13 deletions

diff --git a/ChangeLog b/ChangeLog
index ef78b1df..c2238ab8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2008-05-03  Hans Boehm <Hans.Boehm@hp.com>
+
+	* doc/gcinterface.html: Improve C++ interface documentation.
+
 2008-03-10  Hans Boehm <Hans.Boehm@hp.com>
 
 	* allchblk.c (GC_allochblk): Check for overflow during size
diff --git a/doc/gcinterface.html b/doc/gcinterface.html
index 74230aa6..312d37f4 100644
--- a/doc/gcinterface.html
+++ b/doc/gcinterface.html
@@ -106,7 +106,7 @@ On some platforms, it is necessary to invoke this
 <I>from the main executable, not from a dynamic library,</i> before
 the initial invocation of a GC routine.  It is recommended that this be done
 in portable code, though we try to ensure that it expands to a no-op
-on as many platforms as possible.  As of GC 7.0, it is required if
+on as many platforms as possible.  In GC 7.0, it was required if
 thread-local allocation is enabled in the collector build, and <TT>malloc</tt>
 is not redirected to <TT>GC_malloc</tt>.
 <DT> <B> void GC_gcollect(void) </b>
@@ -206,16 +206,18 @@ proper repair requires platform hooks.)
 The easiest way to ensure that collectable objects are properly referenced
 is to allocate only collectable objects.  This requires that every
 allocation go through one of the following interfaces, each one of
-which replaces a standard C++ allocation mechanism:
+which replaces a standard C++ allocation mechanism.  Note that
+this requires that all STL containers be explicitly instantiated with
+<TT>gc_allocator</tt>.
 <DL>
 <DT> <B> STL allocators </b>
 <DD>
 <P>
-Recent versions of the collector also include a more standard-conforming
+Recent versions of the collector include a hopefully standard-conforming
 allocator implementation in <TT>gc_allocator.h</tt>.  It defines
 <UL>
-<LI> traceable_allocator
-<LI> gc_allocator
+<LI> <TT>traceable_allocator</tt>
+<LI> <TT>gc_allocator</tt>
 </ul>
 which may be used either directly to allocate memory or to instantiate
 container templates. 
@@ -226,26 +228,26 @@ These should work with any fully standard-conforming C++ compiler.
 <P>
 Users of the <A HREF="http://www.sgi.com/tech/stl">SGI extended STL</a>
 or its derivatives (including most g++ versions)
-can alternatively include <TT>new_gc_alloc.h</tt> before including
-STL header files.
+may instead be able to include <TT>new_gc_alloc.h</tt> before including
+STL header files.  This is increasingly discouraged.
 (<TT>gc_alloc.h</tt> corresponds to now obsolete versions of the
 SGI STL.)  This interface is no longer recommended, but it has existed
 for much longer.
 <P>
 This defines SGI-style allocators
 <UL>
-<LI> alloc
-<LI> single_client_alloc
-<LI> gc_alloc
-<LI> single_client_gc_alloc
+<LI> <TT>alloc</tt>
+<LI> <TT>single_client_alloc</tt>
+<LI> <TT>gc_alloc</tt>
+<LI> <TT>single_client_gc_alloc</tt>
 </ul>
 The first two allocate uncollectable but traced
 memory, while the second two allocate collectable memory.
-The single_client versions are not safe for concurrent access by
+The <TT>single_client</tt> versions are not safe for concurrent access by
 multiple threads, but are faster.
 <P>
 For an example, click <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_alloc_exC.txt">here</a>.
-<DT> <B> Class inheritance based interface </b>
+<DT> <B> Class inheritance based interface for new-based allocation</b>
 <DD>
 Users may include gc_cpp.h and then cause members of classes to
 be allocated in garbage collectable memory by having those classes