chromium/src
0
Fork 0
Code Activity

Mostly minor changes such as adding <code></code> around elements, a little rewriting, and a few new documentation bits to pp_var.h. Mostly trying to ensure consistency across all docs and doing cleanup.

Browse Source 
Review URL: http://codereview.chromium.org/7241024

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@91221 0039d316-1c4b-4281-b951-d872f2087c98
This commit is contained in:
jond@google.com
2011-06-30 22:57:17 +00:00
parent 898a81a5bb
commit c549595105
9 changed files with 144 additions and 89 deletions

9
ppapi/c/pp_bool.h

@ -1,4 +1,4 @@
/* Copyright (c) 2010 The Chromium Authors. All rights reserved.
/* Copyright (c) 2011 The Chromium Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*/
@ -9,7 +9,8 @@
/**
* @file
* This file defines the PP_Bool enumeration for use in PPAPI C headers.
* This file defines the <code>PP_Bool</code> enumeration for use in PPAPI C
* headers.
*/
/**
@ -19,8 +20,8 @@
*/
/**
* The PP_Bool enum is a boolean value for use in PPAPI C headers. The
* standard bool type is not available to pre-C99 compilers, and is not
* The <code>PP_Bool</code> enum is a boolean value for use in PPAPI C headers.
* The standard bool type is not available to pre-C99 compilers, and is not
* guaranteed to be compatible between C and C++, whereas the PPAPI C
* headers can be included from C or C++ code.
*/

2
ppapi/c/pp_errors.h

@ -29,7 +29,7 @@ enum {
/**
* This value is returned by a function that accepts a PP_CompletionCallback
* and cannot complete synchronously. This code indicates that the given
* and cannot complete synchronously. This code indicates that the given
* callback will be asynchronously notified of the final result once it is
* available.
*/

38
ppapi/c/pp_input_event.h

@ -94,7 +94,8 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_InputEvent_Modifier, 4);
*/
/**
* The PP_InputEvent_Key struct represents a key up or key down event.
* The <code>PP_InputEvent_Key</code> struct represents a key up or key down
* event.
*
* Key up and key down events correspond to physical keys on the keyboard. The
* actual character that the user typed (if any) will be delivered in a
@ -114,7 +115,7 @@ struct PP_InputEvent_Key {
uint32_t modifier;
/**
* |key_code| reflects the DOM KeyboardEvent |keyCode| field.
* This value reflects the DOM KeyboardEvent <code>keyCode</code> field.
* Chrome populates this with the Windows-style Virtual Key code of the key.
*/
@ -131,7 +132,8 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Key, 8);
*/
/**
* The PP_InputEvent_Character struct represents a typed character event.
* The <code>PP_InputEvent_Character</code> struct represents a typed character
* event.
*
* Normally, the program will receive a key down event, followed by a character
* event, followed by a key up event. The character event will have any
@ -151,7 +153,7 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Key, 8);
* isn't lost"), 'R' character event, 'R' key up.
*/
struct PP_InputEvent_Character {
/** A combination of the EVENT_MODIFIER flags. */
/** A combination of the <code>PP_InputEvent_Modifier</code> flags. */
uint32_t modifier;
/**
@ -173,17 +175,20 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Character, 12);
*/
/**
* The PP_InputEvent_Mouse struct represents all mouse events except
* mouse wheel events.
* The <code>PP_InputEvent_Mouse</code> struct represents all mouse events
* except mouse wheel events.
*/
struct PP_InputEvent_Mouse {
/** This value is a bit field combination of the EVENT_MODIFIER flags. */
/**
* This value is a bit field combination of the
* <code>PP_InputEvent_Modifier</code> flags.
*/
uint32_t modifier;
/**
* This value represents the button that changed for mouse down or up events.
* This value will be PP_EVENT_MOUSEBUTTON_NONE for mouse move, enter, and
* leave events.
* This value will be <code>PP_EVENT_MOUSEBUTTON_NONE</code> for mouse move,
* enter, and leave events.
*/
PP_InputEvent_MouseButton button;
@ -222,10 +227,14 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Mouse, 20);
*/
/**
* The PP_InputEvent_Wheel struct represents all mouse wheel events.
* The <code>PP_InputEvent_Wheel</code> struct represents all mouse wheel
* events.
*/
struct PP_InputEvent_Wheel {
/** This value represents a combination of the EVENT_MODIFIER flags. */
/**
* This value represents a combination of the <code>EVENT_MODIFIER</code>
* flags.
*/
uint32_t modifier;
/**
@ -258,7 +267,7 @@ struct PP_InputEvent_Wheel {
* The number of "clicks" of the scroll wheel that have produced the
* event. The value may have system-specific acceleration applied to it,
* depending on the device. The positive and negative meanings are the same
* as for |delta|.
* as for <code>delta_x</code> and <code>delta_y</code>.
*
* If you are scrolling, you probably want to use the delta values above.
* These tick events can be useful if you aren't doing actual scrolling and
@ -278,8 +287,9 @@ struct PP_InputEvent_Wheel {
float wheel_ticks_y;
/**
* Indicates if the scroll delta_x/delta_y indicates pages or lines to
* scroll by. When true, the user is requesting to scroll by pages.
* Indicates if the scroll <code>delta_x</code>/<code>delta_y</code>
* indicates pages or lines to scroll by. When true, the user is requesting
* to scroll by pages.
*/
PP_Bool scroll_by_page;
};

8
ppapi/c/pp_point.h

@ -1,4 +1,4 @@
/* Copyright (c) 2010 The Chromium Authors. All rights reserved.
/* Copyright (c) 2011 The Chromium Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*/
@ -47,13 +47,13 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Point, 8);
*/
/**
* PP_MakePoint() creates a PP_Point given the x and y coordinates as int32_t
* values.
* 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 PP_Point structure.
* @return A <code>PP_Point</code> structure.
*/
PP_INLINE struct PP_Point PP_MakePoint(int32_t x, int32_t y) {
struct PP_Point ret;

13
ppapi/c/pp_rect.h

@ -1,4 +1,4 @@
/* Copyright (c) 2010 The Chromium Authors. All rights reserved.
/* Copyright (c) 2011 The Chromium Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*/
@ -21,7 +21,8 @@
*/
/**
* The PP_Rect struct contains the size and location of a 2D rectangle.
* The <code>PP_Rect</code> struct contains the size and location of a 2D
* rectangle.
*/
struct PP_Rect {
@ -45,15 +46,17 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Rect, 16);
*/
/**
* PP_MakeRectFromXYWH() creates a PP_Rect given x and y coordinates and width
* and height dimensions as int32_t values.
* PP_MakeRectFromXYWH() creates a <code>PP_Rect</code> given x and y
* coordinates and width and height dimensions 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.
* @param[in] w An int32_t value representing a width.
* @param[in] h An int32_t value representing a height.
* @return A PP_Rect structure.
*
* @return A <code>PP_Rect</code> structure.
*/
PP_INLINE struct PP_Rect PP_MakeRectFromXYWH(int32_t x, int32_t y,
int32_t w, int32_t h) {

13
ppapi/c/pp_resource.h

@ -1,4 +1,4 @@
/* Copyright (c) 2010 The Chromium Authors. All rights reserved.
/* Copyright (c) 2011 The Chromium Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*/
@ -10,8 +10,8 @@
/**
* @file
* This file defines the PP_Resource type which represents data associated with
* the module.
* This file defines the <code>PP_Resource</code> type which represents data
* associated with the module.
*/
/**
@ -29,9 +29,10 @@
* the DOM, a resource has no meaning or visibility outside of the module
* interface.
*
* Resources are reference counted. Use AddRefResource and ReleaseResource in
* ppb_core.h to manage the reference count of a resource. The data will be
* automatically destroyed when the internal reference count reaches 0.
* Resources are reference counted. Use <code>AddRefResource()</code>
* and <code>ReleaseResource()</code> in <code>ppb_core.h</code> to manage the
* reference count of a resource. The data will be automatically destroyed when
* the internal reference count reaches 0.
*/
typedef int32_t PP_Resource;
PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_Resource, 4);

11
ppapi/c/pp_size.h

@ -7,7 +7,7 @@
/**
* @file
* This file defines the width and height of a 2 dimensional rectangle.
* This file defines the width and height of a 2D rectangle.
*/
#include "ppapi/c/pp_macros.h"
@ -19,7 +19,7 @@
*/
/**
* The PP_Size struct contains the size of a 2D rectangle.
* The <code>PP_Size</code> struct contains the size of a 2D rectangle.
*/
struct PP_Size {
/** This value represents the width of the rectangle. */
@ -38,10 +38,13 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Size, 8);
*/
/**
* PP_MakeSize() creates a PP_Size given a width and height as int32_t values.
* PP_MakeSize() creates a <code>PP_Size</code> given a width and height as
* int32_t values.
*
* @param[in] w An int32_t value representing a width.
* @param[in] h An int32_t value representing a height.
* @return A PP_Size structure.
*
* @return A <code>PP_Size</code> structure.
*/
PP_INLINE struct PP_Size PP_MakeSize(int32_t w, int32_t h) {
struct PP_Size ret;

18
ppapi/c/pp_time.h

@ -1,4 +1,4 @@
/* Copyright (c) 2010 The Chromium Authors. All rights reserved.
/* Copyright (c) 2011 The Chromium Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*/
@ -17,9 +17,9 @@
* @{
*/
/**
* The PP_Time type represents the "wall clock time" according to the browser
* and is defined as the number of seconds since the Epoch (00:00:00 UTC,
* January 1, 1970).
* The <code>PP_Time</code> type represents the "wall clock time" according
* to the browser and is defined as the number of seconds since the Epoch
* (00:00:00 UTC, January 1, 1970).
*/
typedef double PP_Time;
PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_Time, 8);
@ -32,11 +32,11 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_Time, 8);
* @{
*/
/**
* A PP_TimeTicks value represents time ticks which are measured in seconds
* and are used for indicating the time that certain messages were received.
* In contrast to PP_Time, PP_TimeTicks does not correspond to any actual
* wall clock time and will not change discontinuously if the user changes
* their computer clock.
* A <code>PP_TimeTicks</code> value represents time ticks which are measured
* in seconds and are used for indicating the time that certain messages were
* received. In contrast to <code>PP_Time</code>, <code>PP_TimeTicks</code>
* does not correspond to any actual wall clock time and will not change
* discontinuously if the user changes their computer clock.
*
* The units are in seconds, but are not measured relative to any particular
* epoch, so the most you can do is compare two values.

121
ppapi/c/pp_var.h

@ -1,4 +1,4 @@
/* Copyright (c) 2010 The Chromium Authors. All rights reserved.
/* Copyright (c) 2011 The Chromium Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*/
@ -22,8 +22,8 @@
*/
/**
* PP_VarType is an enumeration of the different types that can be contained
* within a PP_VAR structure.
* The <code>PP_VarType</code> is an enumeration of the different types that
* can be contained within a <code>PP_Var</code> structure.
*/
typedef enum {
/**
@ -33,35 +33,36 @@ typedef enum {
/**
* A NULL value. This is similar to undefined, but JavaScript differentiates
* the two so we expose it here as well.
* the two so it is exposed here as well.
*/
PP_VARTYPE_NULL,
/**
* A boolean value, use the as_bool member of the var.
* A boolean value, use the <code>as_bool</code> member of the var.
*/
PP_VARTYPE_BOOL,
/**
* A 32-bit integer value. Use the as_int member of the var.
* A 32-bit integer value. Use the <code>as_int</code> member of the var.
*/
PP_VARTYPE_INT32,
/**
* A double-precision floating point value. Use the as_double member of the
* var.
* A double-precision floating point value. Use the <code>as_double</code>
* member of the var.
*/
PP_VARTYPE_DOUBLE,
/**
* The Var represents a string. The as_id field is used to identify the
* string, which may be created and retrieved from the PPB_Var interface.
* The Var represents a string. The <code>as_id</code> field is used to
* identify the string, which may be created and retrieved from the
* <code>PPB_Var</code> interface.
*/
PP_VARTYPE_STRING,
/**
* Represents a JavaScript object. This vartype is not currently usable
* from plugins, although it is used internally for some tasks.
* from modules, although it is used internally for some tasks.
*/
PP_VARTYPE_OBJECT,
@ -69,7 +70,7 @@ typedef enum {
* Arrays and dictionaries are not currently supported but will be added
* in future revisions. These objects are reference counted so be sure
* to properly AddRef/Release them as you would with strings to ensure your
* plugin will continue to work with future versions of the API.
* module will continue to work with future versions of the API.
*/
PP_VARTYPE_ARRAY,
PP_VARTYPE_DICTIONARY
@ -85,38 +86,65 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_VarType, 4);
*/
/**
* The PP_VAR struct is a variant data type and can contain any
* value of one of the types named in the PP_VarType enum. This structure is
* for passing data between native code which can be strongly typed and the
* browser (JavaScript) which isn't strongly typed.
* The <code>PP_VAR</code> struct is a variant data type and can contain any
* value of one of the types named in the <code>PP_VarType</code> enum. This
* structure is for passing data between native code which can be strongly
* typed and the browser (JavaScript) which isn't strongly typed.
*
* JavaScript has a "number" type for holding a number, and does not
* differentiate between floating point and integer numbers. The
* JavaScript operations will try to optimize operations by using
* integers when possible, but could end up with doubles. Therefore,
* you can't assume a numeric PP_Var will be the type you expect.
* you can't assume a numeric <code>PP_Var</code> will be the type you expect.
* Your code should be capable of handling either int32_t or double for numeric
* PP_Vars sent from JavaScript.
*/
struct PP_Var {
PP_VarType type;
/** Ensures @a value is aligned on an 8-byte boundary relative to the
* start of the struct. Some compilers align doubles on 8-byte boundaries
* for 32-bit x86, and some align on 4-byte boundaries.
/**
* The <code>padding</code> ensures <code>value</code> is aligned on an
* 8-byte boundary relative to the start of the struct. Some compilers
* align doubles on 8-byte boundaries for 32-bit x86, and some align on
* 4-byte boundaries.
*/
int32_t padding;
/**
* This <code>value</code> represents the contents of the PP_Var. Only one of
* the fields of <code>value</code> is valid at a time based upon
* <code>type</code>.
*/
union {
/**
* If <code>type</code> is <code>PP_VARTYPE_BOOL</code>,
* <code>as_bool</code> represents the value of this <code>PP_Var</code> as
* <code>PP_Bool</code>.
*/
PP_Bool as_bool;
/**
* If <code>type</code> is <code>PP_VARTYPE_INT32</code>,
* <code>as_int</code> represents the value of this <code>PP_Var</code> as
* <code>int32_t</code>.
*/
int32_t as_int;
/**
* If <code>type</code> is <code>PP_VARTYPE_DOUBLE</code>,
* <code>as_double</code> represents the value of this <code>PP_Var</code>
* as <code>double</code>.
*/
double as_double;
/**
* Internal ID for strings objects, arrays, and dictionaries. The
* identifier is an opaque handle assigned by the browser to the plugin. It
* is guaranteed never to be 0, so a plugin can initialize this ID to 0 to
* indicate a "NULL handle."
* If <code>type</code> is <code>PP_VARTYPE_STRING</code>,
* <code>PP_VARTYPE_OBJECT</code>, <code>PP_VARTYPE_ARRAY</code>, or
* <code>PP_VARTYPE_DICTIONARY</code>,
* <code>as_id</code> represents the value of this <code>PP_Var</code> as
* an opaque handle assigned by the browser. This handle is guaranteed
* never to be 0, so a module can initialize this ID to 0 to indicate a
* "NULL handle."
*/
int64_t as_id;
} value;
@ -132,9 +160,10 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Var, 16);
*/
/**
* PP_MakeUndefined() is a utility function used to wrap an undefined value
* into a PP_VAR struct for passing to the browser.
* @return A PP_Var structure
* PP_MakeUndefined() is used to wrap an undefined value into a
* <code>PP_Var</code> struct for passing to the browser.
*
* @return A <code>PP_Var</code> structure.
*/
PP_INLINE struct PP_Var PP_MakeUndefined() {
struct PP_Var result = { PP_VARTYPE_UNDEFINED, 0, {PP_FALSE} };
@ -142,9 +171,10 @@ PP_INLINE struct PP_Var PP_MakeUndefined() {
}
/**
* PP_MakeNull() is a utility function used to wrap a null value into a
* PP_VAR struct for passing to the browser.
* @return A PP_Var structure
* PP_MakeNull() is used to wrap a null value into a
* <code>PP_Var</code> struct for passing to the browser.
*
* @return A <code>PP_Var</code> structure,
*/
PP_INLINE struct PP_Var PP_MakeNull() {
struct PP_Var result = { PP_VARTYPE_NULL, 0, {PP_FALSE} };
@ -152,10 +182,13 @@ PP_INLINE struct PP_Var PP_MakeNull() {
}
/**
* PP_MakeBool() is a utility function used to wrap a boolean value into a
* PP_VAR struct for passing to the browser.
* @param[in] value A PP_Bool enumeration
* @return A PP_Var structure
* PP_MakeBool() is used to wrap a boolean value into a
* <code>PP_Var</code> struct for passing to the browser.
*
* @param[in] value A <code>PP_Bool</code> enumeration to
* wrap.
*
* @return A <code>PP_Var</code> structure.
*/
PP_INLINE struct PP_Var PP_MakeBool(PP_Bool value) {
struct PP_Var result = { PP_VARTYPE_BOOL, 0, {PP_FALSE} };
@ -164,10 +197,12 @@ PP_INLINE struct PP_Var PP_MakeBool(PP_Bool value) {
}
/**
* PP_MakeInt32() is a utility function used to wrap a 32 bit integer value
* into a PP_VAR struct for passing to the browser.
* @param[in] value An int32
* @return A PP_Var structure
* PP_MakeInt32() is used to wrap a 32 bit integer value
* into a <code>PP_Var</code> struct for passing to the browser.
*
* @param[in] value An int32 to wrap.
*
* @return A <code>PP_Var</code> structure.
*/
PP_INLINE struct PP_Var PP_MakeInt32(int32_t value) {
struct PP_Var result = { PP_VARTYPE_INT32, 0, {PP_FALSE} };
@ -176,10 +211,12 @@ PP_INLINE struct PP_Var PP_MakeInt32(int32_t value) {
}
/**
* PP_MakeDouble() is a utility function used to wrap a double value into a
* PP_VAR struct for passing to the browser.
* @param[in] value A double
* @return A PP_Var structure
* PP_MakeDouble() is used to wrap a double value into a
* <code>PP_Var</code> struct for passing to the browser.
*
* @param[in] value A double to wrap.
*
* @return A <code>PP_Var</code> structure.
*/
PP_INLINE struct PP_Var PP_MakeDouble(double value) {
struct PP_Var result = { PP_VARTYPE_DOUBLE, 0, {PP_FALSE} };