This fixes lots of docs issues in the IDL files.

Review URL: http://codereview.chromium.org/147144

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@19430 0039d316-1c4b-4281-b951-d872f2087c98

16 files changed, 100 insertions, 36 deletions

diff --git a/o3d/plugin/idl/bounding_box.idl b/o3d/plugin/idl/bounding_box.idl
index 1904f59..b41b86c 100644
--- a/o3d/plugin/idl/bounding_box.idl
+++ b/o3d/plugin/idl/bounding_box.idl
@@ -74,13 +74,14 @@ class BoundingBox {
     Multiplies the bounding box by the given matrix returning a new bounding
     box.
     \param matrix The matrix to multiply by.
-    \returns The new bounding box.
+    \return The new bounding box.
   %]
   [const, userglue] BoundingBox Mul(Vectormath::Aos::Matrix4 matrix);
 
   %[
     Adds a bounding box to this bounding box returning a bounding box that
     encompases both.
+    \param box BoundingBox to add to this BoundingBox.
     \return The new bounding box.
   %]
   [const, userglue] BoundingBox Add(BoundingBox box);
diff --git a/o3d/plugin/idl/buffer.idl b/o3d/plugin/idl/buffer.idl
index 0124c7b..f639934 100644
--- a/o3d/plugin/idl/buffer.idl
+++ b/o3d/plugin/idl/buffer.idl
@@ -57,8 +57,9 @@ class Buffer : NamedObject {
     \param field_type type of data in the field. Valid types are "FloatField",
         "UInt32Field", "UByteNField".
     \param num_components number of components in the field.
+    \return The created field.
   %]
-  [userglue]
+  [userglue, noreturndocs]
   Field? CreateField(String field_type, unsigned int num_components);
 
   %[
@@ -186,7 +187,6 @@ class VertexBufferBase : Buffer {
 
     \param start_index index of first value to set.
     \param values Values to be stored in the buffer starting at index.
-    \return True if operation was successful.
   %]
   [nocpp, userglue] void SetAt(unsigned int start_index, float[] values);
 
@@ -382,7 +382,6 @@ class SourceBuffer : VertexBufferBase {
 
     \param start_index index of first value to set.
     \param values Values to be stored in the buffer starting at index.
-    \return True if operation was successful.
   %]
   [nocpp, userglue] void SetAt(unsigned int start_index, unsigned int[] values);
 
diff --git a/o3d/plugin/idl/canvas.idl b/o3d/plugin/idl/canvas.idl
index 013349a..a9b61fe 100644
--- a/o3d/plugin/idl/canvas.idl
+++ b/o3d/plugin/idl/canvas.idl
@@ -48,7 +48,7 @@ class Canvas : ParamObject {
     Sets the size of the bitmap area that the Canvas uses.
     \param width The width of the bitmap.
     \param height The height of the bitmap.
-    \returns true if the Canvas surface was allocated successfully.
+    \return true if the Canvas surface was allocated successfully.
   %]
   bool SetSize(int width, int height);
 
@@ -156,6 +156,7 @@ class Canvas : ParamObject {
     Copies the contents of the Canvas to a 2D texture object. The size of the
     texture must match exactly the size of the Canvas set by the setSize() method.
     The format of the texture must be set to either ARGB8 or XRGB8.
+    \param texture Texture to copy to.
   %]
   void CopyToTexture(Texture2D texture);
 
diff --git a/o3d/plugin/idl/canvas_paint.idl b/o3d/plugin/idl/canvas_paint.idl
index 94c3812..c6f9f9f 100644
--- a/o3d/plugin/idl/canvas_paint.idl
+++ b/o3d/plugin/idl/canvas_paint.idl
@@ -126,6 +126,7 @@ class CanvasPaint : ParamObject {
 
   %[
     Returns metrics describing the font currently set on this paint object.
+    \return The font metrics.
   %]
   CanvasFontMetrics GetFontMetrics();
 
@@ -134,6 +135,7 @@ class CanvasPaint : ParamObject {
     The bounds are returned as an array containing [left, top, right, bottom]
     values relative to (0, 0).
     \param text The string of text to be measured.
+    \return The bounds of text.
   %]
  Float4 MeasureText(String text);
 
diff --git a/o3d/plugin/idl/client.idl b/o3d/plugin/idl/client.idl
index 439f63b..f30b0e4 100644
--- a/o3d/plugin/idl/client.idl
+++ b/o3d/plugin/idl/client.idl
@@ -138,7 +138,7 @@ class Client {
     \param id The id of the object to look for.
     \return The object or null if a object with the given id is not found.
   %]
-  [const] ObjectBase? GetObjectById(Id id);
+  [const, noreturndocs] ObjectBase? GetObjectById(Id id);
 
   %[
     Searches the Client for objects of a particular name and type.
@@ -146,14 +146,14 @@ class Client {
     \param class_name name of class to look for.
     \return Array of objects found.
   %]
-  [const] ObjectArray GetObjects(String name, String class_name);
+  [const, noretundocs] ObjectArray GetObjects(String name, String class_name);
 
   %[
     Searches the Client for objects of a particular type.
     \param class_name name of class to look for.
     \return Array of objects found.
   %]
-  [const] ObjectArray GetObjectsByClassName(String class_name);
+  [const, noreturndocs] ObjectArray GetObjectsByClassName(String class_name);
 
   %[
     \var RenderMode,
@@ -192,12 +192,15 @@ class Client {
 
     This function can only be called from inside a render callback. If you call
     it the client will not do its default call as mentioned above.
+
+    \param render_node root RenderNode to start rendering from.
   %]
   void RenderTree(RenderNode render_node);
 
   %[
     Returns an array of DisplayModes which are available for use in full-screen
     mode.
+    \return An array of DisplayModes.
   %]
   [userglue, plugin_data] DisplayMode[] GetDisplayModes();
 
@@ -209,11 +212,15 @@ class Client {
     how to scale it.  There can be only one full-screen click region at a time;
     calling this again will override any previous call.
 
-    Returns true on success, false if the mode_id is invalid.
+    \param x x position in pixels.
+    \param y y position in pixels.
+    \param width width in pixels.
+    \param height height in pixels.
+    \param mode_id Id of mode to use.
   %]
   [userglue, plugin_data]
-  void SetFullscreenClickRegion(int x, int y, int width, int height, int
-      mode_id);
+  void SetFullscreenClickRegion(
+      int x, int y, int width, int height, int mode_id);
   %[
     Deactivates the plugin click region that was previously created with
     SetFullscreenClickRegion().
@@ -338,12 +345,16 @@ class Client {
     There can be only one callback for a given event type at a time; setting a
     new one deletes the old one.
 
+    \param type Type of event to set callback for.
+    \param handler Function to call on event.
+
     \sa Event for a list of event
   %]
   void SetEventCallback(String type, EventCallback? handler);
 
   %[
     Removes the previously-registered callback for an event of the given type.
+    \param type Type of event to clear callback for.
   %]
   void ClearEventCallback(String type);
 
@@ -433,6 +444,8 @@ class Client {
 
   %[
     This function is only available in the test version of the plugin.
+    \param file_name Name to save screenshot to.
+    \return True on success.
   %]
   bool SaveScreen(String file_name);
 
@@ -456,6 +469,7 @@ class Client {
   %[
     Returns the socket address of the IMC message queue associated with the
     Client.
+    \return The socket address.
   %]
   [const] String GetMessageQueueAddress();
 
@@ -494,6 +508,7 @@ class Client {
 
   %[
     Returns the profiling information as a string.
+    \return The profiling info.
   %]
   String ProfileToString();
 
diff --git a/o3d/plugin/idl/curve.idl b/o3d/plugin/idl/curve.idl
index 0f876f2..66fb45b 100644
--- a/o3d/plugin/idl/curve.idl
+++ b/o3d/plugin/idl/curve.idl
@@ -171,6 +171,7 @@ class Curve : Function {
   %[
     Returns whether or not the curve is discontinuous. A discontinuous curve
     takes more time to evaluate.
+    \return True if the curve is discontinuous.
   %]
   [const] bool IsDiscontinuous();
 
diff --git a/o3d/plugin/idl/effect.idl b/o3d/plugin/idl/effect.idl
index 3066a20..808671e 100644
--- a/o3d/plugin/idl/effect.idl
+++ b/o3d/plugin/idl/effect.idl
@@ -138,6 +138,7 @@ typedef EffectStreamInfo[] EffectStreamInfoArray;
     that only work on both platforms. That format is mostly CG.
 
     \param effect the code of the effect.
+    \return True if successful.
   %]
   [virtual, pure] bool LoadFromFXString(String effect);
 
diff --git a/o3d/plugin/idl/element.idl b/o3d/plugin/idl/element.idl
index e18ae2e..27ec977 100644
--- a/o3d/plugin/idl/element.idl
+++ b/o3d/plugin/idl/element.idl
@@ -104,11 +104,12 @@ typedef DrawElement[] DrawElementArray;
     Shape.createDrawElements and Transform.createDrawElements this one will
     create more than one element for the same material.
 
-    \param pack: pack used to manage created DrawElement.
-    \param material: material to use for DrawElement. If you pass null
+    \param pack pack used to manage created DrawElement.
+    \param material material to use for DrawElement. If you pass null
         it will use the material on this Element. This allows you to easily
         setup the default (just draw as is) by passing null or setup a shadow
         pass by passing in a shadow material.
+    \return The created draw element.
   %]
   DrawElement CreateDrawElement(Pack pack,
                                 Material? material);
diff --git a/o3d/plugin/idl/field.idl b/o3d/plugin/idl/field.idl
index df3ca41..4c68b9b 100644
--- a/o3d/plugin/idl/field.idl
+++ b/o3d/plugin/idl/field.idl
@@ -84,6 +84,7 @@ class FloatField : Field {
 
     \param start_index index of the first value to get.
     \param num_elements number of elements to read from field.
+    \return The values of the field.
   %]
   [userglue] float[] GetAt(unsigned int start_index, unsigned int num_elements);
 
@@ -141,6 +142,7 @@ class UInt32Field : Field {
 
     \param start_index index of the first value to get.
     \param num_elements number of elements to read from field.
+    \return The values of the field.
   %]
   [userglue] unsigned int[] GetAt(unsigned int start_index,
                                   unsigned int num_elements);
@@ -201,6 +203,7 @@ class UByteNField : Field {
 
     \param start_index index of the first value to get.
     \param num_elements number of elements to read from field.
+    \return The values of the field.
   %]
   [userglue] float[] GetAt(unsigned int start_index, unsigned int num_elements);
 
diff --git a/o3d/plugin/idl/named.idl b/o3d/plugin/idl/named.idl
index f9fc4c4..3401cfc 100644
--- a/o3d/plugin/idl/named.idl
+++ b/o3d/plugin/idl/named.idl
@@ -71,7 +71,8 @@ class ObjectBase {
   t.isAClassName('o3d.ParamObject');  // true
   t.isAClassName('o3d.Shape');        // false
   \endcode
-  \returns true if this object is a or is derived from the given class name.
+  \param class_name Name of class to check for.
+  \return true if this object is a or is derived from the given class name.
   %]
   bool IsAClassName(String class_name);
 
diff --git a/o3d/plugin/idl/pack.idl b/o3d/plugin/idl/pack.idl
index 460d2c6..99b4863 100644
--- a/o3d/plugin/idl/pack.idl
+++ b/o3d/plugin/idl/pack.idl
@@ -71,8 +71,6 @@ typedef ObjectBase[] ObjectArray;
     Textures, Effects, Materials, for example. That means the moment you call
     pack.destroy() those objects will be freed. If the client then tries to
     render and some objects are missing you'll immediately get an error.
-
-    \return True if the pack was successfully deleted.
   %]
   void Destroy();
 
@@ -165,7 +163,7 @@ typedef ObjectBase[] ObjectArray;
         \li o3d.TRSToMatrix4
     \return The created object.
   %]
-  ObjectBase? CreateObject(String type_name);
+  [noreturndocs] ObjectBase? CreateObject(String type_name);
 
   %[
     Creates a new Texture2D object of the specified size and format and
@@ -179,16 +177,16 @@ typedef ObjectBase[] ObjectArray;
     \param format The memory format of each texel
     \param levels The number of mipmap levels.  Use zero to create the compelete
          mipmap chain.
-    \param enable_render_surfaces: If true, the texture object will expose
+    \param enable_render_surfaces If true, the texture object will expose
          RenderSurface objects through GetRenderSurface(...).
     \return The Texture2D object.
 
   %]
   Texture2D? CreateTexture2D(int width,
-                            int height,
-                            Texture::Format format,
-                            int levels,
-                            bool enable_render_surfaces);
+                             int height,
+                             Texture::Format format,
+                             int levels,
+                             bool enable_render_surfaces);
 
   %[
     Creates a new TextureCUBE object of the specified size and format and
@@ -232,9 +230,10 @@ typedef ObjectBase[] ObjectArray;
     \param class_type_name the Class of the object. It is okay to pass base
          types for example "o3d.RenderNode" will return ClearBuffers,
          DrawPasses, etc...
-    \returns Array of Objects.
+    \return Array of Objects.
   %]
-  [const] ObjectArray GetObjects(String name, String class_type_name);
+  [const, noreturndocs]
+  ObjectArray GetObjects(String name, String class_type_name);
 
   %[
     Search the pack for all objects of a certain class
@@ -246,9 +245,10 @@ typedef ObjectBase[] ObjectArray;
     \param class_type_name the Class of the object. It is okay to pass base
          types for example "o3d.RenderNode" will return ClearBuffers,
          DrawPasses, etc...
-    \returns Array of Objects.
+    \return Array of Objects.
   %]
-  [const] ObjectArray GetObjectsByClassName(String class_type_name);
+  [const, noreturndocs]
+  ObjectArray GetObjectsByClassName(String class_type_name);
 
   %[
     All the objects managed by this pack.
@@ -271,7 +271,7 @@ typedef ObjectBase[] ObjectArray;
   %[
     Creates a FileRequest to be used to asynchronously load a Texture.
     \param type Must be "TEXTURE"
-    \returns a FileRequest
+    \return a FileRequest
   %]
   [noccp, userglue] FileRequest? CreateFileRequest(String type);
   [verbatim=cpp_glue, include="core/cross/file_request.h"] %{
@@ -287,7 +287,7 @@ typedef ObjectBase[] ObjectArray;
 
   %[
     Creates an ArchiveRequest so we can stream in assets from an archive
-    \returns an ArchiveRequest
+    \return an ArchiveRequest
   %]
   [noccp, userglue] ArchiveRequest CreateArchiveRequest();
   [verbatim=cpp_glue, include="import/cross/archive_request.h"] %{
@@ -299,7 +299,10 @@ typedef ObjectBase[] ObjectArray;
 
   %[
     Creates a Texture given a RawData object
-    \returns the Texture
+    \param raw_data The RawData to create the texture from.
+    \param generate_mips True if you want O3D to generate mip maps for the
+        texture.
+    \return the Texture
   %]
   Texture? CreateTextureFromRawData(RawData raw_data,
                                     bool generate_mips);
diff --git a/o3d/plugin/idl/param.idl b/o3d/plugin/idl/param.idl
index f0a4705..09e21db 100644
--- a/o3d/plugin/idl/param.idl
+++ b/o3d/plugin/idl/param.idl
@@ -88,7 +88,6 @@ typedef Param[] ParamVector;
     Breaks a specific param-bind output connection on this param.
 
     \param destination_param param to unbind.
-    \return True if the param was a destination param and was unbound.
   %]
   void UnbindOutput(Param destination_param);
 
diff --git a/o3d/plugin/idl/param_object.idl b/o3d/plugin/idl/param_object.idl
index cac6efd..f8b8993 100644
--- a/o3d/plugin/idl/param_object.idl
+++ b/o3d/plugin/idl/param_object.idl
@@ -91,7 +91,8 @@ class ParamObject : NamedObject {
          \li 'o3d.WorldViewProjectionInverseTransposeParamMatrix4'
     \return The newly created Param or null on failure.
   %]
-  [userglue] Param? CreateParam(String param_name, String param_type_name);
+  [userglue, noreturndocs]
+  Param? CreateParam(String param_name, String param_type_name);
 
   %[
     Searches by name for a Param defined in the object.
@@ -99,7 +100,8 @@ class ParamObject : NamedObject {
     \param param_name Name to search for.
     \return The Param with the given name, or null otherwise.
   %]
-  [userglue, const] Param? GetParam(String param_name);
+  [userglue, const, noreturndocs]
+  Param? GetParam(String param_name);
 
   %[
     Removes a Param from a ParamObject.
diff --git a/o3d/plugin/idl/shape.idl b/o3d/plugin/idl/shape.idl
index 1423e94..b72f88f 100644
--- a/o3d/plugin/idl/shape.idl
+++ b/o3d/plugin/idl/shape.idl
@@ -63,7 +63,7 @@ typedef Element[] ElementArray;
     Creates a DrawElement for each Element owned by this Shape.
     If an Element already has a DrawElement that uses \a material a new
     DrawElement will not be created.
-    \param pack: pack used to manage created DrawElements.
+    \param pack pack used to manage created DrawElements.
     \param material material to use for each DrawElement. If you pass null it
         will use the material on the corresponding Element.
         This allows you to easily setup the default (just draw as is) by passing
diff --git a/o3d/plugin/idl/texture.idl b/o3d/plugin/idl/texture.idl
index 7039a9e..014f77e 100644
--- a/o3d/plugin/idl/texture.idl
+++ b/o3d/plugin/idl/texture.idl
@@ -124,8 +124,8 @@ namespace o3d {
   %[
     Returns a RenderSurface object associated with a mip_level of a texture.
 
-    \param mip_level: The mip-level of the surface to be returned.
-    \param pack: The pack in which the surface will reside.
+    \param mip_level The mip-level of the surface to be returned.
+    \param pack The pack in which the surface will reside.
     \return The RenderSurface object.
   %]
   RenderSurface? GetRenderSurface(int mip_level, Pack pack);
@@ -422,7 +422,7 @@ coordinates.
 
     \param face The cube face from which to extract the surface.
     \param mip_level The mip-level of the surface to be returned.
-    \param pack: The pack in which the surface will reside.
+    \param pack The pack in which the surface will reside.
     \return The RenderSurface object.
   %]
   RenderSurface? GetRenderSurface(CubeFace face, int mip_level, Pack pack);
diff --git a/o3d/plugin/idl/vector.idl b/o3d/plugin/idl/vector.idl
index 84dd4f1..2d7d988 100644
--- a/o3d/plugin/idl/vector.idl
+++ b/o3d/plugin/idl/vector.idl
@@ -35,6 +35,10 @@
 namespace Vectormath {
 namespace Aos {
 
+%[
+  A data type representing a 3d direction. A Vector3 is represented in
+  JavaScript by an array containing 3 numbers: [x, y, z].
+%]
 [binding_model=by_value, marshaled, nocpp, include=
     "third_party/vectormath/files/vectormathlibrary/include/vectormath/scalar/cpp/vectormath_aos.h"]
 class Vector3 {
@@ -59,6 +63,10 @@ class Vector3 {
   %}
 };
 
+%[
+  A data type representing a 3d point. A Point3 is represented in
+  JavaScript by an array containing 3 numbers: [x, y, z].
+%]
 [binding_model=by_value, marshaled, nocpp, include=
     "third_party/vectormath/files/vectormathlibrary/include/vectormath/scalar/cpp/vectormath_aos.h"]
 class Point3 {
@@ -82,6 +90,10 @@ class Point3 {
   %}
 };
 
+%[
+  A data type representing a 4 value Vector. A Vector4 is represented in
+  JavaScript by an array containing 4 numbers: [x, y, z, w].
+%]
 [binding_model=by_value, marshaled, nocpp, include=
     "third_party/vectormath/files/vectormathlibrary/include/vectormath/scalar/cpp/vectormath_aos.h"]
 class Vector4 {
@@ -106,6 +118,15 @@ class Vector4 {
   %}
 };
 
+%[
+  A data type representing a 3x3 Matrix. A Matrix3 is represented in JavaScript
+  by an array containing 3 arrays of 3 numbers each:
+  \code
+  [[x0, y0, z0],
+   [x1, y1, z1],
+   [x2, y2, z2]]
+  \endcode
+%]
 [binding_model=by_value, marshaled, nocpp, include=
     "third_party/vectormath/files/vectormathlibrary/include/vectormath/scalar/cpp/vectormath_aos.h"]
 class Matrix3 {
@@ -130,6 +151,16 @@ class Matrix3 {
   %}
 };
 
+%[
+  A data type representing a 4x4 Matrix. A Matrix4 is represented in JavaScript
+  by an array containing 4 arrays of 4 numbers each:
+  \code
+  [[x0, y0, z0, w0],
+   [x1, y1, z1, w1],
+   [x2, y2, z2, w2],
+   [x3, y3, z3, w3]]
+  \endcode
+%]
 [binding_model=by_value, marshaled, nocpp, include=
     "third_party/vectormath/files/vectormathlibrary/include/vectormath/scalar/cpp/vectormath_aos.h"]
 class Matrix4 {
@@ -154,6 +185,10 @@ class Matrix4 {
   %}
 };
 
+%[
+  A data type representing a Quaterion. A Quat is represented in JavaScript
+  by an array containing 4 numbers: [x, y, z, w]
+%]
 [binding_model=by_value, marshaled, nocpp, include=
     "third_party/vectormath/files/vectormathlibrary/include/vectormath/scalar/cpp/vectormath_aos.h"]
 class Quat {