Formatting changes

Fixes to some of the C documentation in the IDL.
Review URL: http://codereview.chromium.org/7308010

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

ppapi/api/pp_bool.idl

@@ -22,6 +22,10 @@
 #inline cc
 /**
  * Converts a C++ "bool" type to a PP_Bool.
+ *
+ * @param[in] b A C++ "bool" type.
+ *
+ * @return A PP_Bool.
  */
 inline PP_Bool PP_FromBool(bool b) {
   return b ? PP_TRUE : PP_FALSE;
@@ -29,6 +33,10 @@ inline PP_Bool PP_FromBool(bool b) {
 
 /**
  * Converts a PP_Bool to a C++ "bool" type.
+ *
+ * @param[in] b A PP_Bool.
+ *
+ * @return A C++ "bool" type.
  */
 inline bool PP_ToBool(PP_Bool b) {
   return (b != PP_FALSE);

ppapi/api/pp_completion_callback.idl

@@ -8,15 +8,14 @@
  */
 
 /**
- * PP_CompletionCallback_Func defines the function signature that you implement
- * to receive callbacks on asynchronous completion of an operation.
+ * This typedef defines the signature that you implement to receive callbacks
+ * on asynchronous completion of an operation.
  *
- * |user_data| is a pointer to user-specified data associated with this
- * function at callback creation. See PP_MakeCompletionCallback() for details.
- *
- * |result| is the result of the operation. Non-positive values correspond to
- * the error codes from pp_errors.h (excluding PP_OK_COMPLETIONPENDING).
- * Positive values indicate additional information such as bytes read.
+ * @param[in] user_data A pointer to user data passed to a callback function.
+ * @param[in] result If result is 0 (PP_OK), the operation succeeded.  Negative
+ * values (other than -1 or PP_OK_COMPLETE) indicate error and are specified
+ * in pp_errors.h. Positive values for result usually indicate success and have
+ * some operation-dependent meaning (such as bytes read).
  */
 typedef void PP_CompletionCallback_Func([inout] mem_t user_data,
                                         [in] int32_t result);
@@ -52,17 +51,36 @@ enum PP_CompletionCallback_Flag {
 
 
 /**
- * Any method that takes a PP_CompletionCallback can complete asynchronously.
- * Refer to PP_CompletionCallback_Flag for more information.
- *
- * If PP_CompletionCallback_Func is NULL, the operation might block if necessary
- * to complete the work. Refer to PP_BlockUntilComplete for more information.
+ * Any method that takes a <code>PP_CompletionCallback</code> has the option of
+ * completing asynchronously if the operation would block.  Such a method
+ * should return <code>PP_OK_COMPLETIONPENDING</code> to indicate that the
+ * method will complete asynchronously and notify the caller and will always be
+ * invoked from the main thread of PPAPI execution.  If the completion callback
+ * is NULL, then the operation will block if necessary to complete its work.
+ * <code>PP_BlockUntilComplete()</code> provides a convenient way to specify
+ * blocking behavior. Refer to <code>PP_BlockUntilComplete</code> for more
+ * information.
  *
- * See PP_MakeCompletionCallback() for the description of each field.
+ * The result parameter passed to <code>func</code> is an int32_t that, if
+ * negative indicates an error code whose meaning is specific to the calling
+ * method (refer to <code>pp_error.h</code> for further information). A
+ * positive or 0 value is a return result indicating success whose meaning
+ * depends on the calling method (e.g. number of bytes read).
  */
 [passByValue] struct PP_CompletionCallback {
+  /**
+   * This value is a callback function that will be called.
+   */
   PP_CompletionCallback_Func func;
+  /**
+   * This value is a pointer to user data passed to a callback function.
+   */
   mem_t user_data;
+
+  /**
+   * Flags used to control how non-NULL callbacks are scheduled by
+   * asynchronous methods.
+   */
   int32_t flags;
 };
 
@@ -74,20 +92,23 @@ enum PP_CompletionCallback_Flag {
  * @{
  */
 /**
- * PP_MakeCompletionCallback() is used to create a PP_CompletionCallback
- * without flags. If you want to alter the default callback behavior, set the
- * flags to a bit field combination of PP_CompletionCallback_Flag's.
+ * PP_MakeCompletionCallback() is used to create a
+ * <code>PP_CompletionCallback</code>.
+ *
+ * <strong>Example:</strong>
  *
- * Example:
+ * <code>
  * struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL);
  * cc.flags = cc.flags | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL;
+ * </code>
  *
- * @param[in] func A PP_CompletionCallback_Func to be called on completion.
- * @param[in] user_data A pointer to user data passed to be passed to the
- * callback function. This is optional and is typically used to help track state
- * in case of multiple pending callbacks.
+ * @param[in] func A <code>PP_CompletionCallback_Func</code> that will be
+ * called.
+ * @param[in] user_data A pointer to user data passed to your callback
+ * function. This is optional and is typically used to help track state
+ * when you may have multiple callbacks pending.
  *
- * @return A PP_CompletionCallback structure.
+ * @return A <code>PP_CompletionCallback</code> structure.
  */
 PP_INLINE struct PP_CompletionCallback PP_MakeCompletionCallback(
     PP_CompletionCallback_Func func,
@@ -131,7 +152,8 @@ PP_INLINE struct PP_CompletionCallback PP_MakeOptionalCompletionCallback(
  * the callback function passing it user data specified on creation and
  * completion |result|.
  *
- * @param[in] cc A pointer to a PP_CompletionCallback that will be run.
+ * @param[in] cc A pointer to a <code>PP_CompletionCallback</code> that will be
+ * run.
  * @param[in] result The result of the operation. Non-positive values correspond
  * to the error codes from pp_errors.h (excluding PP_OK_COMPLETIONPENDING).
  * Positive values indicate additional information such as bytes read.
@@ -156,24 +178,24 @@ PP_INLINE void PP_RunCompletionCallback(struct PP_CompletionCallback* cc,
  * until the function completes. Blocking completion callbacks are only allowed
  * from background threads.
  *
- * @return A PP_CompletionCallback structure corresponding to a NULL callback.
+ * @return A <code>PP_CompletionCallback</code> structure.
  */
 PP_INLINE struct PP_CompletionCallback PP_BlockUntilComplete() {
   return PP_MakeCompletionCallback(NULL, NULL);
 }
 
 /**
- * Runs a callback and clears the reference to it.
- *
- * This is used when the null-ness of a completion callback is used as a signal
- * for whether a completion callback has been registered. In this case, after
- * the execution of the callback, it should be cleared.
+ * PP_RunAndClearCompletionCallback() runs a callback and clears the reference
+ * to that callback.
  *
- * However, this introduces a conflict if the completion callback wants to
- * schedule more work that involves the same completion callback again (for
- * example, when reading data from an URLLoader, one would typically queue up
- * another read callback). As a result, this function clears the pointer
- * *before* the given callback is executed.
+ * This function is used when the null-ness of a completion callback is used as
+ * a signal for whether a completion callback has been registered. In this
+ * case, after the execution of the callback, it should be cleared. However,
+ * this introduces a conflict if the completion callback wants to schedule more
+ * work that involves the same completion callback again (for example, when
+ * reading data from an URLLoader, one would typically queue up another read
+ * callback). As a result, this function clears the pointer
+ * before the provided callback is executed.
  */
 PP_INLINE void PP_RunAndClearCompletionCallback(
     struct PP_CompletionCallback* cc,

ppapi/api/pp_input_event.idl

@@ -128,10 +128,9 @@ struct PP_InputEvent_Mouse {
   uint32_t modifier;
 
   /**
-   * Indicates the amount vertically and horizontally the user has requested
-   * to scroll by with their mouse wheel. A scroll down or to the right (where
-   * the content moves up or left) is represented as positive values, and
-   * a scroll up or to the left (where the content moves down or right) is
+   * The mouse wheel's horizontal scroll amount. A scroll to the right
+   * (where the content moves left) is represented as positive values,
+   * and a scroll to the left (where the content moves right) is
    * represented as negative values.
    *
    * The units are either in pixels (when scroll_by_page is false) or pages
@@ -150,7 +149,25 @@ struct PP_InputEvent_Mouse {
    */
   float_t delta_x;
 
-  /** This value represents */
+  /**
+   * The mouse wheel's vertical scroll amount. A scroll down (where the
+   * content moves up) is represented as positive values, and a scroll up
+   * (where the content moves down) is represented as negative values.
+   *
+   * The units are either in pixels (when scroll_by_page is false) or pages
+   * (when scroll_by_page is true). For example, delta_y = -3 means scroll up 3
+   * pixels when scroll_by_page is false, and scroll up 3 pages when
+   * scroll_by_page is true.
+   *
+   * This amount is system dependent and will take into account the user's
+   * preferred scroll sensitivity and potentially also nonlinear acceleration
+   * based on the speed of the scrolling.
+   *
+   * Devices will be of varying resolution. Some mice with large detents will
+   * only generate integer scroll amounts. But fractional values are also
+   * possible, for example, on some trackpads and newer mice that don't have
+   * "clicks".
+   */
   float_t delta_y;
 
   /**

ppapi/api/pp_point.idl

@@ -45,10 +45,12 @@ struct PP_FloatPoint {
 /**
  * PP_MakePoint() creates a <code>PP_Point</code> given the x and y coordinates
  * as int32_t values.
+ *
  * @param[in] x An int32_t value representing a horizontal coordinate of a
  * point, starting with 0 as the left-most coordinate.
  * @param[in] y An int32_t value representing a vertical coordinate of a point,
  * starting with 0 as the top-most coordinate.
+ *
  * @return A <code>PP_Point</code> structure.
  */
 PP_INLINE struct PP_Point PP_MakePoint(int32_t x, int32_t y) {

ppapi/c/pp_bool.h

@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From pp_bool.idl modified Sat Jul 16 16:50:26 2011. */
+/* From pp_bool.idl modified Wed Aug 10 15:19:02 2011. */
 
 #ifndef PPAPI_C_PP_BOOL_H_
 #define PPAPI_C_PP_BOOL_H_
@@ -39,6 +39,10 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_Bool, 4);
 #ifdef __cplusplus
 /**
  * Converts a C++ "bool" type to a PP_Bool.
+ *
+ * @param[in] b A C++ "bool" type.
+ *
+ * @return A PP_Bool.
  */
 inline PP_Bool PP_FromBool(bool b) {
   return b ? PP_TRUE : PP_FALSE;
@@ -46,6 +50,10 @@ inline PP_Bool PP_FromBool(bool b) {
 
 /**
  * Converts a PP_Bool to a C++ "bool" type.
+ *
+ * @param[in] b A PP_Bool.
+ *
+ * @return A C++ "bool" type.
  */
 inline bool PP_ToBool(PP_Bool b) {
   return (b != PP_FALSE);

ppapi/c/pp_completion_callback.h

@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From pp_completion_callback.idl modified Sat Jul 16 16:50:26 2011. */
+/* From pp_completion_callback.idl modified Thu Aug 11 14:45:09 2011. */
 
 #ifndef PPAPI_C_PP_COMPLETION_CALLBACK_H_
 #define PPAPI_C_PP_COMPLETION_CALLBACK_H_
@@ -22,15 +22,14 @@
  * @{
  */
 /**
- * PP_CompletionCallback_Func defines the function signature that you implement
- * to receive callbacks on asynchronous completion of an operation.
+ * This typedef defines the signature that you implement to receive callbacks
+ * on asynchronous completion of an operation.
  *
- * |user_data| is a pointer to user-specified data associated with this
- * function at callback creation. See PP_MakeCompletionCallback() for details.
- *
- * |result| is the result of the operation. Non-positive values correspond to
- * the error codes from pp_errors.h (excluding PP_OK_COMPLETIONPENDING).
- * Positive values indicate additional information such as bytes read.
+ * @param[in] user_data A pointer to user data passed to a callback function.
+ * @param[in] result If result is 0 (PP_OK), the operation succeeded.  Negative
+ * values (other than -1 or PP_OK_COMPLETE) indicate error and are specified
+ * in pp_errors.h. Positive values for result usually indicate success and have
+ * some operation-dependent meaning (such as bytes read).
  */
 typedef void (*PP_CompletionCallback_Func)(void* user_data, int32_t result);
 /**
@@ -78,17 +77,35 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_CompletionCallback_Flag, 4);
  * @{
  */
 /**
- * Any method that takes a PP_CompletionCallback can complete asynchronously.
- * Refer to PP_CompletionCallback_Flag for more information.
- *
- * If PP_CompletionCallback_Func is NULL, the operation might block if necessary
- * to complete the work. Refer to PP_BlockUntilComplete for more information.
+ * Any method that takes a <code>PP_CompletionCallback</code> has the option of
+ * completing asynchronously if the operation would block.  Such a method
+ * should return <code>PP_OK_COMPLETIONPENDING</code> to indicate that the
+ * method will complete asynchronously and notify the caller and will always be
+ * invoked from the main thread of PPAPI execution.  If the completion callback
+ * is NULL, then the operation will block if necessary to complete its work.
+ * <code>PP_BlockUntilComplete()</code> provides a convenient way to specify
+ * blocking behavior. Refer to <code>PP_BlockUntilComplete</code> for more
+ * information.
  *
- * See PP_MakeCompletionCallback() for the description of each field.
+ * The result parameter passed to <code>func</code> is an int32_t that, if
+ * negative indicates an error code whose meaning is specific to the calling
+ * method (refer to <code>pp_error.h</code> for further information). A
+ * positive or 0 value is a return result indicating success whose meaning
+ * depends on the calling method (e.g. number of bytes read).
  */
 struct PP_CompletionCallback {
+  /**
+   * This value is a callback function that will be called.
+   */
   PP_CompletionCallback_Func func;
+  /**
+   * This value is a pointer to user data passed to a callback function.
+   */
   void* user_data;
+  /**
+   * Flags used to control how non-NULL callbacks are scheduled by
+   * asynchronous methods.
+   */
   int32_t flags;
 };
 /**
@@ -102,20 +119,23 @@ struct PP_CompletionCallback {
  * @{
  */
 /**
- * PP_MakeCompletionCallback() is used to create a PP_CompletionCallback
- * without flags. If you want to alter the default callback behavior, set the
- * flags to a bit field combination of PP_CompletionCallback_Flag's.
+ * PP_MakeCompletionCallback() is used to create a
+ * <code>PP_CompletionCallback</code>.
  *
- * Example:
+ * <strong>Example:</strong>
+ *
+ * <code>
  * struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL);
  * cc.flags = cc.flags | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL;
+ * </code>
  *
- * @param[in] func A PP_CompletionCallback_Func to be called on completion.
- * @param[in] user_data A pointer to user data passed to be passed to the
- * callback function. This is optional and is typically used to help track state
- * in case of multiple pending callbacks.
+ * @param[in] func A <code>PP_CompletionCallback_Func</code> that will be
+ * called.
+ * @param[in] user_data A pointer to user data passed to your callback
+ * function. This is optional and is typically used to help track state
+ * when you may have multiple callbacks pending.
  *
- * @return A PP_CompletionCallback structure.
+ * @return A <code>PP_CompletionCallback</code> structure.
  */
 PP_INLINE struct PP_CompletionCallback PP_MakeCompletionCallback(
     PP_CompletionCallback_Func func,
@@ -159,7 +179,8 @@ PP_INLINE struct PP_CompletionCallback PP_MakeOptionalCompletionCallback(
  * the callback function passing it user data specified on creation and
  * completion |result|.
  *
- * @param[in] cc A pointer to a PP_CompletionCallback that will be run.
+ * @param[in] cc A pointer to a <code>PP_CompletionCallback</code> that will be
+ * run.
  * @param[in] result The result of the operation. Non-positive values correspond
  * to the error codes from pp_errors.h (excluding PP_OK_COMPLETIONPENDING).
  * Positive values indicate additional information such as bytes read.
@@ -184,24 +205,24 @@ PP_INLINE void PP_RunCompletionCallback(struct PP_CompletionCallback* cc,
  * until the function completes. Blocking completion callbacks are only allowed
  * from background threads.
  *
- * @return A PP_CompletionCallback structure corresponding to a NULL callback.
+ * @return A <code>PP_CompletionCallback</code> structure.
  */
 PP_INLINE struct PP_CompletionCallback PP_BlockUntilComplete() {
   return PP_MakeCompletionCallback(NULL, NULL);
 }
 
 /**
- * Runs a callback and clears the reference to it.
+ * PP_RunAndClearCompletionCallback() runs a callback and clears the reference
+ * to that callback.
  *
- * This is used when the null-ness of a completion callback is used as a signal
- * for whether a completion callback has been registered. In this case, after
- * the execution of the callback, it should be cleared.
- *
- * However, this introduces a conflict if the completion callback wants to
- * schedule more work that involves the same completion callback again (for
- * example, when reading data from an URLLoader, one would typically queue up
- * another read callback). As a result, this function clears the pointer
- * *before* the given callback is executed.
+ * This function is used when the null-ness of a completion callback is used as
+ * a signal for whether a completion callback has been registered. In this
+ * case, after the execution of the callback, it should be cleared. However,
+ * this introduces a conflict if the completion callback wants to schedule more
+ * work that involves the same completion callback again (for example, when
+ * reading data from an URLLoader, one would typically queue up another read
+ * callback). As a result, this function clears the pointer
+ * before the provided callback is executed.
  */
 PP_INLINE void PP_RunAndClearCompletionCallback(
     struct PP_CompletionCallback* cc,
@@ -215,3 +236,4 @@ PP_INLINE void PP_RunAndClearCompletionCallback(
  */
 
 #endif  /* PPAPI_C_PP_COMPLETION_CALLBACK_H_ */
+

ppapi/c/pp_input_event.h

@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From pp_input_event.idl modified Wed Jul 20 11:21:44 2011. */
+/* From pp_input_event.idl modified Thu Aug 11 14:47:50 2011. */
 
 #ifndef PPAPI_C_PP_INPUT_EVENT_H_
 #define PPAPI_C_PP_INPUT_EVENT_H_
@@ -137,10 +137,9 @@ struct PP_InputEvent_Wheel {
    */
   uint32_t modifier;
   /**
-   * Indicates the amount vertically and horizontally the user has requested
-   * to scroll by with their mouse wheel. A scroll down or to the right (where
-   * the content moves up or left) is represented as positive values, and
-   * a scroll up or to the left (where the content moves down or right) is
+   * The mouse wheel's horizontal scroll amount. A scroll to the right
+   * (where the content moves left) is represented as positive values,
+   * and a scroll to the left (where the content moves right) is
    * represented as negative values.
    *
    * The units are either in pixels (when scroll_by_page is false) or pages
@@ -158,7 +157,25 @@ struct PP_InputEvent_Wheel {
    * "clicks".
    */
   float delta_x;
-  /** This value represents */
+  /**
+   * The mouse wheel's vertical scroll amount. A scroll down (where the
+   * content moves up) is represented as positive values, and a scroll up
+   * (where the content moves down) is represented as negative values.
+   *
+   * The units are either in pixels (when scroll_by_page is false) or pages
+   * (when scroll_by_page is true). For example, delta_y = -3 means scroll up 3
+   * pixels when scroll_by_page is false, and scroll up 3 pages when
+   * scroll_by_page is true.
+   *
+   * This amount is system dependent and will take into account the user's
+   * preferred scroll sensitivity and potentially also nonlinear acceleration
+   * based on the speed of the scrolling.
+   *
+   * Devices will be of varying resolution. Some mice with large detents will
+   * only generate integer scroll amounts. But fractional values are also
+   * possible, for example, on some trackpads and newer mice that don't have
+   * "clicks".
+   */
   float delta_y;
   /**
    * The number of "clicks" of the scroll wheel that have produced the

ppapi/c/pp_point.h

@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From pp_point.idl modified Sat Jul 16 16:50:26 2011. */
+/* From pp_point.idl modified Wed Aug 10 14:06:40 2011. */
 
 #ifndef PPAPI_C_PP_POINT_H_
 #define PPAPI_C_PP_POINT_H_
@@ -60,10 +60,12 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_FloatPoint, 8);
 /**
  * PP_MakePoint() creates a <code>PP_Point</code> given the x and y coordinates
  * as int32_t values.
+ *
  * @param[in] x An int32_t value representing a horizontal coordinate of a
  * point, starting with 0 as the left-most coordinate.
  * @param[in] y An int32_t value representing a vertical coordinate of a point,
  * starting with 0 as the top-most coordinate.
+ *
  * @return A <code>PP_Point</code> structure.
  */
 PP_INLINE struct PP_Point PP_MakePoint(int32_t x, int32_t y) {

ppapi/c/ppp_instance.h

@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From ppp_instance.idl modified Mon Aug  8 06:46:25 2011. */
+/* From ppp_instance.idl modified Tue Aug  9 09:58:45 2011. */
 
 #ifndef PPAPI_C_PPP_INSTANCE_H_
 #define PPAPI_C_PPP_INSTANCE_H_