Skip to content

GitLab

T
tangled
Commit b6cf7684 authored by jond@google.com's avatar jond@google.com
Browse files
Options

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
parent 172da1b8
Hide whitespace changes
Inline Side-by-side
Showing with 187 additions and 89 deletions
ppapi/api/pp_bool.idl
View file @ b6cf7684
......@@ -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
View file @ b6cf7684
......@@ -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>.
*
* Example:
* struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL);
* cc.flags = cc.flags | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL;
* <strong>Example:</strong>
*
* @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.
* <code>
* struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL);
* cc.flags = cc.flags | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL;
* </code>
*
* @return A PP_CompletionCallback structure.
* @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 <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
View file @ b6cf7684
......@@ -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
View file @ b6cf7684
......@@ -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
View file @ b6cf7684
......@@ -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
View file @ b6cf7684
......@@ -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:
* struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL);
* cc.flags = cc.flags | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL;
* <strong>Example:</strong>
*
* @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.
* <code>
* struct PP_CompletionCallback cc = PP_MakeCompletionCallback(Foo, NULL);
* cc.flags = cc.flags | PP_COMPLETIONCALLBACK_FLAG_OPTIONAL;
* </code>
*
* @return A PP_CompletionCallback structure.
* @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 <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
View file @ b6cf7684
......@@ -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
View file @ b6cf7684
......@@ -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
View file @ b6cf7684
......@@ -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_
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment