Finalize documentation for the automation extension API.

Finalize documentation for the automation extension API.

This duplicates the accessibility enums between accessibility and automation converting to camel casing. It also cleans up some of the idl

For the sake of record, attempts to share the same enum ran into the following issues:
- the docs generator assumes a one-to-one (save camel/snake/unix casing) correspondance between filenames and idl namespaces.
- the handlebar templating language does not allow for logical string comparisons/equality checks or passing in-line string literals, so attempting to in-line names was unsuccessful.
- references to the enums (which were cased for the sake of cpp enums), were incorrect for the docs (which want camel casing).

A local cl with the change is still available  but suffers
from odd filename, casing conflicts, and AX* naming issues.

BUG=309681
Committed: https://src.chromium.org/viewvc/chrome?view=rev&revision=278011

[not at google - send to devlin, 2014-06-13 22:43:40]

structure lgtm, didn't look at the details

[David Tseng, 2014-06-17 03:19:15]

ping @aboxhall?

[aboxhall, 2014-06-17 15:04:19]

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
File chrome/common/extensions/api/automation.idl (right):

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:6: // automation (accessibility)
tree for the browser. The tree resembles the DOM tree, but only exposes
Need to wrap this to 80 cols.

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:11: // Keep the following enums in
sync with 'ui/accessibility/ax_enums.idl'.
Will this comment end up in the compiled documentation? Or does the blank line
keep it out?

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:181: disabled,  // ui/views only
What happens to these comments when the doc is generated?

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:212: [nocompile, noinline_doc]
dictionary AutomationEvent {
Why noinline_doc?

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:219: // Prevent the further bubbling
(or capturing) phases of this event. Note
We should be consistent with either present or imperative tense for the verbs
describing functions. It looks like present tense is the standard in the rest of
the docs.

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:262: // Do the default action based
on this node's role (e.g. click a button).
Present tense.

Do we want to expand on this explanation at all? For example, "This will
generally be the action which would occur if the node was clicked on, such as
pressing a button or selecting a menu option"

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:299: // TODO(aboxhall/dtseng):
implement loading. Kept separate to not include
When do you think we'll end up doing this? We can comment them out or remove
them altogether if you think it might take some time - I know I added them but
it was really just to keep track of where they would go :)

[David Tseng, 2014-06-17 19:25:37]

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
File chrome/common/extensions/api/automation.idl (right):

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:6: // automation (accessibility)
tree for the browser. The tree resembles the DOM tree, but only exposes
On 2014/06/17 15:04:19, aboxhall wrote:
> Need to wrap this to 80 cols.

Done.

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:11: // Keep the following enums in
sync with 'ui/accessibility/ax_enums.idl'.
On 2014/06/17 15:04:18, aboxhall wrote:
> Will this comment end up in the compiled documentation? Or does the blank line
> keep it out?

Nope; didn't show up in preview python server.

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:181: disabled,  // ui/views only
On 2014/06/17 15:04:18, aboxhall wrote:
> What happens to these comments when the doc is generated?

They don't seem to be picked up. I can point you to the preview offline.

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:212: [nocompile, noinline_doc]
dictionary AutomationEvent {
On 2014/06/17 15:04:18, aboxhall wrote:
> Why noinline_doc?

It was inlining the entire definition of AutomationNode for |target| and
omitting AutomationNode as it's own section.

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:219: // Prevent the further bubbling
(or capturing) phases of this event. Note
On 2014/06/17 15:04:19, aboxhall wrote:
> We should be consistent with either present or imperative tense for the verbs
> describing functions. It looks like present tense is the standard in the rest
of
> the docs.

Went with 'Stops' as opposed to 'Prevents' to align with the name and to not
introduce more language than necessary.

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:262: // Do the default action based
on this node's role (e.g. click a button).
On 2014/06/17 15:04:18, aboxhall wrote:
> Present tense.
> 
> Do we want to expand on this explanation at all? For example, "This will
> generally be the action which would occur if the node was clicked on, such as
> pressing a button or selecting a menu option"


Done.

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:299: // TODO(aboxhall/dtseng):
implement loading. Kept separate to not include
On 2014/06/17 15:04:18, aboxhall wrote:
> When do you think we'll end up doing this? We can comment them out or remove
> them altogether if you think it might take some time - I know I added them but
> it was really just to keep track of where they would go :)

Not sure when, but I'm fine with it being here; do you think we should include a
note in the actual docs that this is not yet implemented? I can go either way
for transitioning this API from trunk to dev. It'll be a good reminder for us
when we go from dev to beta if anything.

[aboxhall, 2014-06-17 20:18:12]

lgtm

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
File chrome/common/extensions/api/automation.idl (right):

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:181: disabled,  // ui/views only
On 2014/06/17 19:25:37, David Tseng wrote:
> On 2014/06/17 15:04:18, aboxhall wrote:
> > What happens to these comments when the doc is generated?
> 
> They don't seem to be picked up. I can point you to the preview offline.

No problem, was just curious. I assume we're ok with not having these notes in
our public documentation?

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:212: [nocompile, noinline_doc]
dictionary AutomationEvent {
On 2014/06/17 19:25:37, David Tseng wrote:
> On 2014/06/17 15:04:18, aboxhall wrote:
> > Why noinline_doc?
> 
> It was inlining the entire definition of AutomationNode for |target| and
> omitting AutomationNode as it's own section.

Oh! How annoying.

https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
chrome/common/extensions/api/automation.idl:299: // TODO(aboxhall/dtseng):
implement loading. Kept separate to not include
On 2014/06/17 19:25:36, David Tseng wrote:
> On 2014/06/17 15:04:18, aboxhall wrote:
> > When do you think we'll end up doing this? We can comment them out or remove
> > them altogether if you think it might take some time - I know I added them
but
> > it was really just to keep track of where they would go :)
> 
> Not sure when, but I'm fine with it being here; do you think we should include
a
> note in the actual docs that this is not yet implemented? I can go either way
> for transitioning this API from trunk to dev. It'll be a good reminder for us
> when we go from dev to beta if anything.

I think we should at least make sure |loaded| always returns |true| until load()
is more than a no-op, but we can do that in another CL. Would you mind adding a
note to the TODO to make sure that works before we go to dev?

[David Tseng, 2014-06-17 20:41:13]

On Tue 17 Jun 2014 01:18:12 PM PDT, aboxhall@chromium.org wrote:

 > lgtm
 > 
 > 
 > 
 > 
 >
https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
 > File chrome/common/extensions/api/automation.idl (right):
 > 
 >
https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
 > chrome/common/extensions/api/automation.idl:181: disabled,  // ui/views
 > only
 > On 2014/06/17 19:25:37, David Tseng wrote:
 > > On 2014/06/17 15:04:18, aboxhall wrote:
 > > > What happens to these comments when the doc is generated?
 > 
 > > They don't seem to be picked up. I can point you to the preview
 > offline.
 > 
 > No problem, was just curious. I assume we're ok with not having these
 > notes in our public documentation?
 > 
 >
https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
 > chrome/common/extensions/api/automation.idl:212: [nocompile,
 > noinline_doc] dictionary AutomationEvent {
 > On 2014/06/17 19:25:37, David Tseng wrote:
 > > On 2014/06/17 15:04:18, aboxhall wrote:
 > > > Why noinline_doc?
 > 
 > > It was inlining the entire definition of AutomationNode for |target|
 > and
 > > omitting AutomationNode as it's own section.
 > 
 > Oh! How annoying.
 > 
 >
https://codereview.chromium.org/335923003/diff/1/chrome/common/extensions/api...
 > chrome/common/extensions/api/automation.idl:299: //
 > TODO(aboxhall/dtseng): implement loading. Kept separate to not include
 > On 2014/06/17 19:25:36, David Tseng wrote:
 > > On 2014/06/17 15:04:18, aboxhall wrote:
 > > > When do you think we'll end up doing this? We can comment them out
 > or remove
 > > > them altogether if you think it might take some time - I know I
 > added them but
 > > > it was really just to keep track of where they would go :)
 > 
 > > Not sure when, but I'm fine with it being here; do you think we should
 > include a
 > > note in the actual docs that this is not yet implemented? I can go
 > either way
 > > for transitioning this API from trunk to dev. It'll be a good reminder
 > for us
 > > when we go from dev to beta if anything.
 > 
 > I think we should at least make sure |loaded| always returns |true|
 > until load() is more than a no-op, but we can do that in another CL.
 > Would you mind adding a note to the TODO to make sure that works before
 > we go to dev?

Done (as a separate TODO).
 > 
 > https://codereview.chromium.org/335923003/
 > 

To unsubscribe from this group and stop receiving emails from it, send an email
to chromium-reviews+unsubscribe@chromium.org.

[not at google - send to devlin, 2014-06-17 21:10:31]

mostly rubberstamp lgtm but this documentation won't actually show up until you
add an HTML file for it?

https://codereview.chromium.org/335923003/diff/20001/chrome/common/extensions...
File chrome/common/extensions/api/automation.idl (right):

https://codereview.chromium.org/335923003/diff/20001/chrome/common/extensions...
chrome/common/extensions/api/automation.idl:239: automation.RoleType role;
you shouldn't need to namespace these yourself, it's implicit being within the
same namespace

[David Tseng, 2014-06-17 21:21:32]

On 2014/06/17 21:10:31, kalman wrote:
> mostly rubberstamp lgtm but this documentation won't actually show up until
you
> add an HTML file for it?

Added in intros/automation.html; nothing shows up in the api index because this
api is still marked as trunk channel (so it's a no-op now). I've been testing by
explicitly navigating to the extensions/automation path on the server.

> 
>
https://codereview.chromium.org/335923003/diff/20001/chrome/common/extensions...
> File chrome/common/extensions/api/automation.idl (right):
> 
>
https://codereview.chromium.org/335923003/diff/20001/chrome/common/extensions...
> chrome/common/extensions/api/automation.idl:239: automation.RoleType role;
> you shouldn't need to namespace these yourself, it's implicit being within the
> same namespace

[David Tseng, 2014-06-17 21:21:46]

https://codereview.chromium.org/335923003/diff/20001/chrome/common/extensions...
File chrome/common/extensions/api/automation.idl (right):

https://codereview.chromium.org/335923003/diff/20001/chrome/common/extensions...
chrome/common/extensions/api/automation.idl:239: automation.RoleType role;
On 2014/06/17 21:10:31, kalman wrote:
> you shouldn't need to namespace these yourself, it's implicit being within the
> same namespace

I know...but if I remove it, and refresh the preview, the entire enum gets
inlined here...despite the noinline_doc annotation.

[not at google - send to devlin, 2014-06-17 21:33:01]

On 2014/06/17 21:21:46, David Tseng wrote:
>
https://codereview.chromium.org/335923003/diff/20001/chrome/common/extensions...
> File chrome/common/extensions/api/automation.idl (right):
> 
>
https://codereview.chromium.org/335923003/diff/20001/chrome/common/extensions...
> chrome/common/extensions/api/automation.idl:239: automation.RoleType role;
> On 2014/06/17 21:10:31, kalman wrote:
> > you shouldn't need to namespace these yourself, it's implicit being within
the
> > same namespace
> 
> I know...but if I remove it, and refresh the preview, the entire enum gets
> inlined here...despite the noinline_doc annotation.

You also need to add
chrome/common/extensions/docs/templates/public/extensions/automation.html, have
a look at the other files in that directory.

The inlining of that enum looks like a bug.

[David Tseng, 2014-06-17 22:28:18]

On 2014/06/17 21:33:01, kalman wrote:
> On 2014/06/17 21:21:46, David Tseng wrote:
> >
>
https://codereview.chromium.org/335923003/diff/20001/chrome/common/extensions...
> > File chrome/common/extensions/api/automation.idl (right):
> > 
> >
>
https://codereview.chromium.org/335923003/diff/20001/chrome/common/extensions...
> > chrome/common/extensions/api/automation.idl:239: automation.RoleType role;
> > On 2014/06/17 21:10:31, kalman wrote:
> > > you shouldn't need to namespace these yourself, it's implicit being within
> the
> > > same namespace
> > 
> > I know...but if I remove it, and refresh the preview, the entire enum gets
> > inlined here...despite the noinline_doc annotation.
> 
> You also need to add
> chrome/common/extensions/docs/templates/public/extensions/automation.html,
have
> a look at the other files in that directory.

Yup; done. Still a no-op until we promote to dev.

> 
> The inlining of that enum looks like a bug.

[David Tseng, 2014-06-17 22:43:30]

The CQ bit was checked by dtseng@chromium.org

[commit-bot: I haz the power, 2014-06-17 22:45:31]

CQ is trying da patch. Follow status at
 https://chromium-status.appspot.com/cq/dtseng@chromium.org/335923003/140001

[commit-bot: I haz the power, 2014-06-18 10:14:25]

Change committed as 278011

[not at google - send to devlin, 2014-06-18 20:44:30]

It might not show up in the list, but you can still go to it directly:
https://developer.chrome.com/extensions/automation