[openvrml-commit] openvrml/doc index.doc,1.3,1.4

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/openvrml/openvrml/doc
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv11855/doc

Modified Files:
	index.doc 
Log Message:
Documentation improvements.

Index: index.doc
===================================================================
RCS file: /cvsroot/openvrml/openvrml/doc/index.doc,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** index.doc	9 Aug 2006 01:14:19 -0000	1.3
--- index.doc	25 Oct 2006 22:33:20 -0000	1.4
***************
*** 52,69 ****
   *
   * The resource fetching mechanism can be as full-featured or as spartan as
!  * the user application requires.  A minimal facility might only handle @c
!  * file: URLs.  But in general it is desirable to support at least the schemes
!  * supported by modern Web browsers (significantly, @c ftp: and @c http:).
   *
   * @subsubsection introducing_resource_istream 2.1.2 Introducing resource_istream
   *
!  * OpenVRML accomplishes this extensibility by extending the C++ IOstreams
   * framework.  @c openvrml::resource_istream inherits @c std::istream and adds
   * a few member functions particular to network resource fetching:
   *
   * @code
!  * const std::string url() const throw (std::bad_alloc)
!  * const std::string type() const throw (std::bad_alloc)
!  * bool data_available() const throw ()
   * @endcode
   *
--- 52,69 ----
   *
   * The resource fetching mechanism can be as full-featured or as spartan as
!  * the user application requires.  A minimal facility might only handle
!  * @c file URLs.  But in general it is desirable to support at least the schemes
!  * supported by modern Web browsers (significantly, @c ftp and @c http).
   *
   * @subsubsection introducing_resource_istream 2.1.2 Introducing resource_istream
   *
!  * OpenVRML accomplishes this extensibility by extending the C++ IOStreams
   * framework.  @c openvrml::resource_istream inherits @c std::istream and adds
   * a few member functions particular to network resource fetching:
   *
   * @code
!  * const std::string url() const throw (std::bad_alloc);
!  * const std::string type() const throw (std::bad_alloc);
!  * bool data_available() const throw ();
   * @endcode
   *
***************
*** 76,81 ****
   * The centerpiece of the OpenVRML library is @c openvrml::browser.  This
   * class provides the interface for loading VRML/X3D worlds.  Most management
!  * of the runtime will be handled through its member functions.  Like @c
!  * resource_istream, @c browser is an abstract class that users must inherit.
   * However, @c browser has only one pure virtual function you must implement:
   * the one responsible for creating @c resource_istream%s.
--- 76,81 ----
   * The centerpiece of the OpenVRML library is @c openvrml::browser.  This
   * class provides the interface for loading VRML/X3D worlds.  Most management
!  * of the runtime will be handled through its member functions.  Like
!  * @c resource_istream, @c browser is an abstract class that users must inherit.
   * However, @c browser has only one pure virtual function you must implement:
   * the one responsible for creating @c resource_istream%s.
***************
*** 90,100 ****
   * of your class that implements @c openvrml::resource_istream.
   *
   * @subsubsection resource_istream_impl_considerations 2.1.4 resource_istream implementation considerations
   *
   * OpenVRML supports a notion of data streaming.  In general, network
   * resources are read asynchronously with respect to the rendering thread.
!  * User code that does not support data streaming (as in the example using @c
!  * std::filebuf in the documentation for @c
!  * openvrml::browser::do_get_resource) can remain largely oblivious
   * synchronization issues.  However, user code that supports data streaming
   * must be mindful of the fact that OpenVRML uses separate threads to read the
--- 90,105 ----
   * of your class that implements @c openvrml::resource_istream.
   *
+  * @note Most &ldquo;factory functions&rdquo; (i.e., functions that return an
+  * instance of an object allocated with @c new) in OpenVRML return an
+  * @c auto_ptr.  @c std::auto_ptr is used for ownership transfer; its use for
+  * a return value signals that the caller is taking ownership of the resource.
+  *
   * @subsubsection resource_istream_impl_considerations 2.1.4 resource_istream implementation considerations
   *
   * OpenVRML supports a notion of data streaming.  In general, network
   * resources are read asynchronously with respect to the rendering thread.
!  * User code that does not support data streaming (as in the example using
!  * @c std::filebuf in the documentation for
!  * @c openvrml::browser::do_get_resource) can remain largely oblivious to
   * synchronization issues.  However, user code that supports data streaming
   * must be mindful of the fact that OpenVRML uses separate threads to read the
***************
*** 102,107 ****
   * OpenVRML's stream reading thread is reading the buffer.
   *
!  * The IOstreams framework is typically extended by inheriting @c
!  * std::streambuf to implement new sources and sinks for data.  (Full
   * treatment of this topic is beyond the scope of this document; see <a
   * href="http://www.josuttis.com/libbook/"><i>The C++ Standard Library</i> by
--- 107,112 ----
   * OpenVRML's stream reading thread is reading the buffer.
   *
!  * The IOstreams framework is typically extended by inheriting
!  * @c std::streambuf to implement new sources and sinks for data.  (Full
   * treatment of this topic is beyond the scope of this document; see <a
   * href="http://www.josuttis.com/libbook/"><i>The C++ Standard Library</i> by
***************
*** 110,119 ****
   * IOStreams and Locales</i> by Angelika Langer and Klaus Kreft</a>.)
   * However, <code>std::streambuf</code>'s interface is not thread-safe.  Since
!  * OpenVRML's stream-reading thread can be expected to be using the @c
!  * streambuf interface (by way of the @c std::istream member functions
   * inherited by @c openvrml::resource_istream), it is only safe for user code
   * to use the @c streambuf interface in that same thread; i.e., in code called
   * by OpenVRML.
! 
   * If user code needs to feed data into a buffer in a separate thread, that
   * buffer should not be the one managed by the @c streambuf interface (i.e.,
--- 115,124 ----
   * IOStreams and Locales</i> by Angelika Langer and Klaus Kreft</a>.)
   * However, <code>std::streambuf</code>'s interface is not thread-safe.  Since
!  * OpenVRML's stream-reading thread can be expected to be using the
!  * @c streambuf interface (by way of the @c std::istream member functions
   * inherited by @c openvrml::resource_istream), it is only safe for user code
   * to use the @c streambuf interface in that same thread; i.e., in code called
   * by OpenVRML.
!  *
   * If user code needs to feed data into a buffer in a separate thread, that
   * buffer should not be the one managed by the @c streambuf interface (i.e.,