New and updated documentation.

ppapi/cpp/graphics_3d.h

Index: ppapi/cpp/graphics_3d.h
===================================================================
--- ppapi/cpp/graphics_3d.h	(revision 102517)
+++ ppapi/cpp/graphics_3d.h	(working copy)
@@ -8,62 +8,70 @@
 #include "ppapi/c/ppb_graphics_3d.h"
 #include "ppapi/cpp/resource.h"
 
+/// @file
+/// This file defines the API to create a 3D rendering context in the browser.
 namespace pp {
 
 class CompletionCallback;
 class Instance;
 class Var;
 
+/// This class represents a 3D rendering context in the browser.
 class Graphics3D : public Resource {
  public:
-  /// Creates an is_null() Graphics3D object.
+  /// Default constructor for creating an is_null() Graphics3D object.
   Graphics3D();
 
-  /// Creates and initializes a 3D rendering context. The returned context is
-  /// off-screen to start with. It must be attached to a plugin instance using
-  /// Instance::BindGraphics to draw on the web page.
+  /// A constructor for creating and and initializing a 3D rendering context.
+  /// The returned context is created off-screen and must be attached
+  /// to a module instance using <code>Instance::BindGraphics</code> to draw on
+  /// the web page.
   ///
   /// @param[in] instance The instance that will own the new Graphics3D.
   ///
-  /// @param[in] attrib_list The list of attributes for the context. It is a
-  /// list of attribute name-value pairs in which each attribute is immediately
-  /// followed by the corresponding desired value. The list is terminated with
-  /// PP_GRAPHICS3DATTRIB_NONE. The attrib_list may be NULL or empty
-  /// (first attribute is PP_GRAPHICS3DATTRIB_NONE). If an attribute is not
-  /// specified in attrib_list, then the default value is used (it is said to
-  /// be specified implicitly).
+  /// @param[in] attrib_list The list of attributes (name=value pairs) for the
+  /// context. The list is terminated with
+  /// <code>PP_GRAPHICS3DATTRIB_NONE</code>. The <code>attrib_list</code> may
+  /// be <code>NULL</code> or empty (first attribute is
+  /// <code>PP_GRAPHICS3DATTRIB_NONE</code>). If an attribute is not specified
+  /// in <code>attrib_list</code>, then the default value of 0 is used.

[alokp, 2011/09/27 15:48:30]

Not all default vales are 0.

[jond, 2011/10/11 15:46:52]

Please clarify. All seemed to have Default: 0 in the original file.

[alokp, 2011/10/17 16:30:32]

For PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR, the default value is not 0.

[jond, 2011/10/17 21:32:04]

Done.

[jond, 2011/10/17 21:32:04]

Done.

   ///
-  /// Attributes for the context are chosen according to an attribute-specific
-  /// criteria. Attributes can be classified into two categories:
-  /// - AtLeast: The attribute value in the returned context meets or exceeds
-  ///            the value specified in attrib_list.
-  /// - Exact: The attribute value in the returned context is equal to
-  ///          the value specified in attrib_list.
+  /// Attributes are classified into two categories:
   ///
-  /// Attributes that can be specified in attrib_list include:
-  /// - PP_GRAPHICS3DATTRIB_ALPHA_SIZE: Category: AtLeast Default: 0.
-  /// - PP_GRAPHICS3DATTRIB_BLUE_SIZE: Category: AtLeast Default: 0.
-  /// - PP_GRAPHICS3DATTRIB_GREEN_SIZE: Category: AtLeast Default: 0.
-  /// - PP_GRAPHICS3DATTRIB_RED_SIZE: Category: AtLeast Default: 0.
-  /// - PP_GRAPHICS3DATTRIB_DEPTH_SIZE: Category: AtLeast Default: 0.
-  /// - PP_GRAPHICS3DATTRIB_STENCIL_SIZE: Category: AtLeast Default: 0.
-  /// - PP_GRAPHICS3DATTRIB_SAMPLES: Category: AtLeast Default: 0.
-  /// - PP_GRAPHICS3DATTRIB_SAMPLE_BUFFERS: Category: AtLeast Default: 0.
-  /// - PP_GRAPHICS3DATTRIB_WIDTH: Category: Exact Default: 0.
-  /// - PP_GRAPHICS3DATTRIB_HEIGHT: Category: Exact Default: 0.
-  /// - PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR:
-  ///   Category: Exact Default: Implementation defined.
+  /// 1. AtLeast: The attribute value in the returned context will meet or
+  ///            exceed the value requested when creating the object.
+  /// 2. Exact: The attribute value in the returned context is equal to
+  ///          the value requested when creating the object.
   ///
+  /// AtLeast attributes are (all have default values of 0):
+  ///
+  /// <code>PP_GRAPHICS3DATTRIB_ALPHA_SIZE</code>
+  /// <code>PP_GRAPHICS3DATTRIB_BLUE_SIZE</code>
+  /// <code>PP_GRAPHICS3DATTRIB_GREEN_SIZE</code>
+  /// <code>PP_GRAPHICS3DATTRIB_RED_SIZE</code>
+  /// <code>PP_GRAPHICS3DATTRIB_DEPTH_SIZE</code>
+  /// <code>PP_GRAPHICS3DATTRIB_STENCIL_SIZE</code>
+  /// <code>PP_GRAPHICS3DATTRIB_SAMPLES</code>
+  /// <code>PP_GRAPHICS3DATTRIB_SAMPLE_BUFFERS</code>
+  ///
+  /// Exact attributes are:
+  ///
+  /// <code>PP_GRAPHICS3DATTRIB_WIDTH</code> Default 0
+  /// <code>PP_GRAPHICS3DATTRIB_HEIGHT</code> Default 0
+  /// <code>PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR</code>
+  /// Default: Implementation defined.
+  ///
   /// On failure, the object will be is_null().
   Graphics3D(const Instance* instance,
              const int32_t* attrib_list);
 
-  /// Creates and initializes a 3D rendering context. The returned context is
-  /// off-screen to start with. It must be attached to a plugin instance using
-  /// Instance::BindGraphics to draw on the web page.
+  /// A constructor for creating and initializing a 3D rendering context. The
+  /// returned context is created off-screen. It must be attached to a
+  /// module instance using <code>Instance::BindGraphics</code> to draw on the
+  /// web page.
   ///
-  /// This is identical to the 2-argument version except that this version
-  /// allows sharing of resources with another context.
+  /// This constructor is identical to the 2-argument version except that this
+  /// version allows sharing of resources with another context.
   ///
   /// @param[in] instance The instance that will own the new Graphics3D.
   ///
@@ -74,27 +82,36 @@
   /// can share data in this fashion.
   //
   /// @param[in] attrib_list The list of attributes for the context. See the
-  /// 2-argument version for more information.
+  /// 2-argument version of this constructor for more information.
   ///
   /// On failure, the object will be is_null().
   Graphics3D(const Instance* instance,
              const Graphics3D& share_context,
              const int32_t* attrib_list);
 
+  /// Destructor.
   ~Graphics3D();
 
-  /// Retrieves the value for each attribute in attrib_list. The list
-  /// has the same structure as described for the constructor.
-  /// It is both input and output structure for this function.
+  /// GetAttribs() retrieves the value for each attribute in
+  /// <code>attrib_list</code>. The list has the same structure as described
+  /// for the constructor. All attribute values specified in
+  /// <code>pp_graphics_3d.h</code> can be retrieved.
   ///
-  /// All attributes specified in PPB_Graphics3D.Create can be queried for.
-  /// On failure the following error codes may be returned:
-  /// - PP_ERROR_BADRESOURCE if context is invalid.
-  /// - PP_ERROR_BADARGUMENT if attrib_list is NULL or any attribute in the
-  ///   attrib_list is not a valid attribute.
+  /// @param[in] context The 3D rendering context whose values you want to
+  /// retrieve.
+  /// @param[in/out] attrib_list The list of attributes (name=value pairs) for
+  /// the context. The list is terminated with
+  /// <code>PP_GRAPHICS3DATTRIB_NONE</code>.
   ///
-  /// Example usage: To get the values for rgb bits in the color buffer,
-  /// this function must be called as following:
+  /// The following error codes may be returned on failure:
+  ///
+  /// PP_ERROR_BADRESOURCE if context is invalid.
+  /// PP_ERROR_BADARGUMENT if <code>attrib_list</code> is NULL or any attribute
+  /// in the <code>attrib_list</code> is not a valid attribute.
+  ///
+  /// <strong>Example:</code>
+  ///
+  /// <code>
   /// int attrib_list[] = {PP_GRAPHICS3DATTRIB_RED_SIZE, 0,
   ///                      PP_GRAPHICS3DATTRIB_GREEN_SIZE, 0,
   ///                      PP_GRAPHICS3DATTRIB_BLUE_SIZE, 0,
@@ -103,10 +120,14 @@
   /// int red_bits = attrib_list[1];
   /// int green_bits = attrib_list[3];
   /// int blue_bits = attrib_list[5];
+  /// </code>
+  ///
+  /// This example retrieves the values for rgb bits in the color buffer.

[alokp, 2011/09/27 15:48:30]

Should this line be moved before the example?

[jond, 2011/10/11 15:46:52]

Its okay to introduce the example and then discuss after. 

   int32_t GetAttribs(int32_t* attrib_list) const;
 
-  /// Sets the values for each attribute in attrib_list. The list
-  /// has the same structure as described for PPB_Graphics3D.Create.
+  /// SetAttribs() sets the values for each attribute in
+  /// <code>attrib_list</code>. The list has the same structure as the list
+  /// used in the constructors.
   ///
   /// Attributes that can be specified are:
   /// - PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR
@@ -117,47 +138,55 @@
   ///   attrib_list is not a valid attribute.
   int32_t SetAttribs(int32_t* attrib_list);
 
-  /// Resizes the backing surface for the context.
+  /// ResizeBuffers() resizes the backing surface for the context.
   ///
-  /// On failure the following error codes may be returned:
-  /// - PP_ERROR_BADRESOURCE if context is invalid.
-  /// - PP_ERROR_BADARGUMENT if the value specified for width or height
-  ///   is less than zero.
+  /// @param[in] width The width.

[alokp, 2011/09/27 15:48:30]

The width of backing surface?

[jond, 2011/10/11 15:46:52]

Done.

+  /// @param[in] height The height.
   ///
-  /// If the surface could not be resized due to insufficient resources,
-  /// PP_ERROR_NOMEMORY error is returned on the next SwapBuffers callback.
+  /// @return An int32_t containing <code>PP_ERROR_BADRESOURCE</code> if
+  /// context is invalid or <code>PP_ERROR_BADARGUMENT</code> if the value
+  /// specified for width or height is less than zero.
+  /// <code>PP_ERROR_NOMEMORY</code> might be returned on the next
+  /// SwapBuffers() callback if the surface could not be resized due to
+  /// insufficient resources.
   int32_t ResizeBuffers(int32_t width, int32_t height);
 
-  /// Makes the contents of the color buffer available for compositing.
-  /// This function has no effect on off-screen surfaces - ones not bound
-  /// to any plugin instance. The contents of ancillary buffers are always
-  /// undefined after calling SwapBuffers. The contents of the color buffer are
-  /// undefined if the value of the PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR attribute
-  /// of context is not PP_GRAPHICS3DATTRIB_BUFFER_PRESERVED.
+  /// SwapBuffers() makes the contents of the color buffer available for
+  /// compositing. This function has no effect on off-screen surfaces: surfaces
+  /// not bound to any module instance. The contents of ancillary buffers are
+  /// always undefined after calling SwapBuffers(). The contents of the color
+  /// buffer are undefined if the value of the
+  /// <code>PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR</code> attribute of context is
+  /// not <code>PP_GRAPHICS3DATTRIB_BUFFER_PRESERVED</code>.
   ///
-  /// SwapBuffers runs in asynchronous mode. Specify a callback function and the
-  /// argument for that callback function. The callback function will be
+  /// SwapBuffers() runs in asynchronous mode. Specify a callback function and
+  /// the argument for that callback function. The callback function will be
   /// executed on the calling thread after the color buffer has been composited
-  /// with rest of the html page. While you are waiting for a SwapBuffers
-  /// callback, additional calls to SwapBuffers will fail.
+  /// with rest of the html page. While you are waiting for a SwapBuffers()
+  /// callback, additional calls to SwapBuffers() will fail.
   ///
   /// Because the callback is executed (or thread unblocked) only when the
-  /// plugin's current state is actually on the screen, this function provides a
-  /// way to rate limit animations. By waiting until the image is on the screen
-  /// before painting the next frame, you can ensure you're not generating
-  /// updates faster than the screen can be updated.
+  /// instance's current state is actually on the screen, this function
+  /// provides a way to rate limit animations. By waiting until the image is on
+  /// the screen before painting the next frame, you can ensure you're not
+  /// generating updates faster than the screen can be updated.
   ///
-  /// SwapBuffers performs an implicit flush operation on context.
+  /// SwapBuffers() performs an implicit flush operation on context.
   /// If the context gets into an unrecoverable error condition while
   /// processing a command, the error code will be returned as the argument
   /// for the callback. The callback may return the following error codes:
-  /// - PP_ERROR_NOMEMORY
-  /// - PP_ERROR_CONTEXT_LOST
-  /// Note that the same error code may also be obtained by calling GetError.
   ///
-  /// On failure SwapBuffers may return the following error codes:
-  /// - PP_ERROR_BADRESOURCE if context is invalid.
-  /// - PP_ERROR_BADARGUMENT if callback is invalid.
+  /// <code>PP_ERROR_NOMEMORY</code>
+  /// <code>PP_ERROR_CONTEXT_LOST</code>
+  ///
+  /// Note that the same error code may also be obtained by calling GetError().
+  ///
+  /// param[in] cc A <code>CompletionCallback</code> to be called upon
+  /// completion of SwapBuffers().
+  ///
+  /// @return An int32_t containing <code>PP_ERROR_BADRESOURCE</code> if
+  /// context is invalid or <code>PP_ERROR_BADARGUMENT</code> if callback is
+  /// invalid.
   int32_t SwapBuffers(const CompletionCallback& cc);
 };