Updating documentation

Committed: http://src.chromium.org/viewvc/chrome?view=rev&revision=73683

[jond, 2011-02-02 20:07:19]

Making my way through the docs and either filling in missing docs, or modifying
existing docs.

[David Springer, 2011-02-02 20:09:54]

Have you run this on the try bots?  ALl the changes seem to be localized to
comments, but running this CL through the try bots will shake out any spurious
typos...

[jond, 2011-02-02 20:57:22]

I ran them and they said they failed. But I'm not sure if I can tell
how/where. Is there a way to find out what went wrong?

- Jon

On Wed, Feb 2, 2011 at 1:09 PM, <dspringer@google.com> wrote:

> Have you run this on the try bots?  ALl the changes seem to be localized to
> comments, but running this CL through the try bots will shake out any
> spurious
> typos...
>
>
> http://codereview.chromium.org/6312098/
>

[piman, 2011-02-02 21:02:15]

On 2011/02/02 20:57:22, jond wrote:
> I ran them and they said they failed. But I'm not sure if I can tell
> how/where. Is there a way to find out what went wrong?

You removed PP_ERROR_USERCANCEL (recent addition... badly resolved merge
conflict ?), breaking some code that needs it.


> 
> - Jon
> 
> On Wed, Feb 2, 2011 at 1:09 PM, <mailto:dspringer@google.com> wrote:
> 
> > Have you run this on the try bots?  ALl the changes seem to be localized to
> > comments, but running this CL through the try bots will shake out any
> > spurious
> > typos...
> >
> >
> > http://codereview.chromium.org/6312098/
> >

[dmichael(do not use this one), 2011-02-02 23:36:51]

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_instance.h
File ppapi/c/pp_instance.h (right):

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_instance.h#newcode23
ppapi/c/pp_instance.h:23: * The PP_Instance type uniquely identifies one module
instance. There will
'The PP_Instance type' -> 'A PP_Instance value'

Also, I think 'module instance' is slightly confusing.  Maybe 'instance of the
module' would be better?  It's a tricky thing to convey, but the important thing
is that there are 1 or more PP_Instances for each PP_Module.  The PP_Module maps
to a particular module (a .nexe or a plugin library), and a PP_Instance maps to
an <embed> tag.  There can be multiple <embed> tags on a page that refer to the
same module, and each of those will have exactly 1 PP_Instance.  They may share
1 PP_Module and be in the same address space (but they might not).

It's a tricky concept to describe in words, I think...  so I'll leave it to you
;-)

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_module.h
File ppapi/c/pp_module.h (right):

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_module.h#newcode24
ppapi/c/pp_module.h:24: * The PP_Module type uniquely identifies one module
library.
'The PP_Module type' -> 'A PP_Module value'

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_point.h
File ppapi/c/pp_point.h (right):

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_point.h#newcode10
ppapi/c/pp_point.h:10: * This file defines the APIs to create a 2 dimensional
point on the screen.
s/APIs/API
s/create/represent
s/on the screen/in the module's portal (???)
(Maybe Dave S can help me with the right words;  it's the portion of the page
that the module can draw in, but not necessarily the screen.)

Or...  just eliminate ' on the screen'

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_point.h#newcode11
ppapi/c/pp_point.h:11: * 0,0 is the upper-left corner of the screen.
s/screen/drawing window (???)

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_point.h#newcode26
ppapi/c/pp_point.h:26: */
Not 'on the screen'

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_point.h#newcode29
ppapi/c/pp_point.h:29: * screen.
not 'on the screen', counting from 0 on the left.

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_point.h#newcode33
ppapi/c/pp_point.h:33: /* This value represents the vertical coordinate of a
point on the screen. */
not 'on the screen', counting from 0 at the top.

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_point.h#newcode47
ppapi/c/pp_point.h:47: * PP_MakePoint() places two 32 bit integers inside a
PP_Point structure.
I'd rather wording like:
'creates a PP_Point given the x and y coordinates as int32_t values.'

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_rect.h
File ppapi/c/pp_rect.h (right):

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_rect.h#newcode28
ppapi/c/pp_rect.h:28: /** This value represents the x and y coordinates of the
rectangle. */
of the upper left corner of the rectangle.

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_rect.h#newcode45
ppapi/c/pp_rect.h:45: * PP_MakeRectFromXYWH() places four 32 bit integers inside
a PP_Rect
wording more like 'creates a PP_Rect from ...'

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_rect.h#newcode47
ppapi/c/pp_rect.h:47: * @param[in] x A 32 bit value representing a horizontal
coordinate on the
s/'A 32 bit'/'An int32_t'

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_size.h
File ppapi/c/pp_size.h (right):

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_size.h#newcode41
ppapi/c/pp_size.h:41: * PP_MakeSize() places two 32 bit integers inside a
PP_Size structure.
wording like 'creates a PP_Size...'

[jond, 2011-02-03 17:28:11]

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_instance.h
File ppapi/c/pp_instance.h (right):

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_instance.h#newcode23
ppapi/c/pp_instance.h:23: * The PP_Instance type uniquely identifies one module
instance. There will
 * The PP_Instance value uniquely identifies one instance of a module
 * (.nexe/PP_Module). There will be one module instance for every
 * \<embed> tag on a page.

On 2011/02/02 23:36:51, dmichael wrote:
> 'The PP_Instance type' -> 'A PP_Instance value'
> 
> Also, I think 'module instance' is slightly confusing.  Maybe 'instance of the
> module' would be better?  It's a tricky thing to convey, but the important
thing
> is that there are 1 or more PP_Instances for each PP_Module.  The PP_Module
maps
> to a particular module (a .nexe or a plugin library), and a PP_Instance maps
to
> an <embed> tag.  There can be multiple <embed> tags on a page that refer to
the
> same module, and each of those will have exactly 1 PP_Instance.  They may
share
> 1 PP_Module and be in the same address space (but they might not).
> 
> It's a tricky concept to describe in words, I think...  so I'll leave it to
you
> ;-)

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_module.h
File ppapi/c/pp_module.h (right):

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_module.h#newcode24
ppapi/c/pp_module.h:24: * The PP_Module type uniquely identifies one module
library.
On 2011/02/02 23:36:51, dmichael wrote:
> 'The PP_Module type' -> 'A PP_Module value'

Done.

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_point.h
File ppapi/c/pp_point.h (right):

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_point.h#newcode10
ppapi/c/pp_point.h:10: * This file defines the APIs to create a 2 dimensional
point on the screen.
On 2011/02/02 23:36:51, dmichael wrote:
> s/APIs/API
> s/create/represent
> s/on the screen/in the module's portal (???)
> (Maybe Dave S can help me with the right words;  it's the portion of the page
> that the module can draw in, but not necessarily the screen.)
> 
> Or...  just eliminate ' on the screen'

Done.

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_point.h#newcode11
ppapi/c/pp_point.h:11: * 0,0 is the upper-left corner of the screen.
On 2011/02/02 23:36:51, dmichael wrote:
> s/screen/drawing window (???)

Done.

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_point.h#newcode26
ppapi/c/pp_point.h:26: */
On 2011/02/02 23:36:51, dmichael wrote:
> Not 'on the screen'

Done.

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_point.h#newcode29
ppapi/c/pp_point.h:29: * screen.
On 2011/02/02 23:36:51, dmichael wrote:
> not 'on the screen', counting from 0 on the left.

Done.

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_point.h#newcode33
ppapi/c/pp_point.h:33: /* This value represents the vertical coordinate of a
point on the screen. */
On 2011/02/02 23:36:51, dmichael wrote:
> not 'on the screen', counting from 0 at the top.

Done.

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_point.h#newcode47
ppapi/c/pp_point.h:47: * PP_MakePoint() places two 32 bit integers inside a
PP_Point structure.
On 2011/02/02 23:36:51, dmichael wrote:
> I'd rather wording like:
> 'creates a PP_Point given the x and y coordinates as int32_t values.'

Done.

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_point.h#newcode47
ppapi/c/pp_point.h:47: * PP_MakePoint() places two 32 bit integers inside a
PP_Point structure.
On 2011/02/02 23:36:51, dmichael wrote:
> I'd rather wording like:
> 'creates a PP_Point given the x and y coordinates as int32_t values.'

Done.

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_rect.h
File ppapi/c/pp_rect.h (right):

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_rect.h#newcode28
ppapi/c/pp_rect.h:28: /** This value represents the x and y coordinates of the
rectangle. */
On 2011/02/02 23:36:51, dmichael wrote:
> of the upper left corner of the rectangle.

Done.

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_rect.h#newcode45
ppapi/c/pp_rect.h:45: * PP_MakeRectFromXYWH() places four 32 bit integers inside
a PP_Rect
On 2011/02/02 23:36:51, dmichael wrote:
> wording more like 'creates a PP_Rect from ...'

Done.

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_rect.h#newcode47
ppapi/c/pp_rect.h:47: * @param[in] x A 32 bit value representing a horizontal
coordinate on the
On 2011/02/02 23:36:51, dmichael wrote:
> s/'A 32 bit'/'An int32_t'

Done.

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_size.h
File ppapi/c/pp_size.h (right):

http://codereview.chromium.org/6312098/diff/5003/ppapi/c/pp_size.h#newcode41
ppapi/c/pp_size.h:41: * PP_MakeSize() places two 32 bit integers inside a
PP_Size structure.
On 2011/02/02 23:36:51, dmichael wrote:
> wording like 'creates a PP_Size...'

Done.

[dmichael(do not use this one), 2011-02-03 17:42:00]

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_module.h
File ppapi/c/pp_module.h (right):

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_module.h#newcode10
ppapi/c/pp_module.h:10: * This file defines the PP_Module value which uniquely
identifies the module
'type' was right, here.

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_rect.h
File ppapi/c/pp_rect.h (right):

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_rect.h#newcode28
ppapi/c/pp_rect.h:28: /** This value represents the upper left corner of the
rectangle. */
Sorry, I think I meant 'the x and y coordinates of the upper left corner' (or
similar)

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_rect.h#newcode46
ppapi/c/pp_rect.h:46: * and h dimensions as int32_t values.
w->width
h->height

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_size.h
File ppapi/c/pp_size.h (right):

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_size.h#newcode10
ppapi/c/pp_size.h:10: * This file defines the width and heigh to of a 2
dimenstional rectangle.
heigh->height
remove 'to '

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_time.h
File ppapi/c/pp_time.h (right):

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_time.h#newcode10
ppapi/c/pp_time.h:10: * This file defines time and time ticks values.
'types' is right here.

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_time.h#newcode35
ppapi/c/pp_time.h:35: * The PP_TimeTicks value represents time ticks which are
measured in seconds
The->A

[jond, 2011-02-03 18:03:14]

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_module.h
File ppapi/c/pp_module.h (right):

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_module.h#newcode10
ppapi/c/pp_module.h:10: * This file defines the PP_Module value which uniquely
identifies the module
On 2011/02/03 17:42:00, dmichael wrote:
> 'type' was right, here.

Done.

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_rect.h
File ppapi/c/pp_rect.h (right):

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_rect.h#newcode28
ppapi/c/pp_rect.h:28: /** This value represents the upper left corner of the
rectangle. */
On 2011/02/03 17:42:00, dmichael wrote:
> Sorry, I think I meant 'the x and y coordinates of the upper left corner' (or
> similar)

Done.

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_rect.h#newcode28
ppapi/c/pp_rect.h:28: /** This value represents the upper left corner of the
rectangle. */
On 2011/02/03 17:42:00, dmichael wrote:
> Sorry, I think I meant 'the x and y coordinates of the upper left corner' (or
> similar)

Done.

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_rect.h#newcode46
ppapi/c/pp_rect.h:46: * and h dimensions as int32_t values.
On 2011/02/03 17:42:00, dmichael wrote:
> w->width
> h->height

Done.

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_size.h
File ppapi/c/pp_size.h (right):

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_size.h#newcode10
ppapi/c/pp_size.h:10: * This file defines the width and heigh to of a 2
dimenstional rectangle.
On 2011/02/03 17:42:00, dmichael wrote:
> heigh->height
> remove 'to '

Done.

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_time.h
File ppapi/c/pp_time.h (right):

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_time.h#newcode35
ppapi/c/pp_time.h:35: * The PP_TimeTicks value represents time ticks which are
measured in seconds
On 2011/02/03 17:42:00, dmichael wrote:
> The->A

Done.

http://codereview.chromium.org/6312098/diff/7002/ppapi/c/pp_time.h#newcode35
ppapi/c/pp_time.h:35: * The PP_TimeTicks value represents time ticks which are
measured in seconds
On 2011/02/03 17:42:00, dmichael wrote:
> The->A

Done.

[dmichael(do not use this one), 2011-02-03 18:15:11]

One little nit, o/w LGTM

http://codereview.chromium.org/6312098/diff/4005/ppapi/c/pp_rect.h
File ppapi/c/pp_rect.h (right):

http://codereview.chromium.org/6312098/diff/4005/ppapi/c/pp_rect.h#newcode29
ppapi/c/pp_rect.h:29: * This value represents the x and y coordinates of
upper-left corner of the
'of upper-left'
->
'of the upper-left'

[jond, 2011-02-03 20:58:14]

http://codereview.chromium.org/6312098/diff/4005/ppapi/c/pp_rect.h
File ppapi/c/pp_rect.h (right):

http://codereview.chromium.org/6312098/diff/4005/ppapi/c/pp_rect.h#newcode29
ppapi/c/pp_rect.h:29: * This value represents the x and y coordinates of
upper-left corner of the
On 2011/02/03 18:15:11, dmichael wrote:
> 'of upper-left'
> ->
> 'of the upper-left'

Done.