Finalize documentation for the automation extension API.

chrome/common/extensions/api/automation.idl

 // Copyright 2014 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.
 
 // The <code>chrome.automation</code> API allows developers to access the
-// automation (accessibility) tree for the browser. This is a tree
-// representation, analogous to the DOM tree, which represents the
-// <em>semantic</em> structure of a page, and can be used to programmatically
-// interact with a page.
+// automation (accessibility) tree for the browser. The tree resembles the DOM tree, but only exposes

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

Need to wrap this to 80 cols.

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

Done.

+// <em>semantic</em> structure of a page. It can be used to programmatically
+// interact with a page by examining names, roles, and states, listening for
+// events, and performing actions on nodes.
 [nocompile] namespace automation {
+  // Keep the following enums in sync with 'ui/accessibility/ax_enums.idl'.

[aboxhall, 2014/06/17 15:04:18]

Will this comment end up in the compiled documentation? Or does the blank line
keep it out?

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

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

+  // They are kept here purely for extension docs generation.
+
+  // Possible events fired on an $(ref:automation.AutomationNode).
+  enum EventType {
+    activedescendantchanged,
+    alert,
+    ariaAttributeChanged,
+    autocorrectionOccured,
+    blur,
+    checkedStateChanged,
+    childrenChanged,
+    focus,
+    hide,
+    hover,
+    invalidStatusChanged,
+    layoutComplete,
+    liveRegionChanged,
+    loadComplete,
+    locationChanged,
+    menuEnd,
+    menuListItemSelected,
+    menuListValueChanged,
+    menuPopupEnd,
+    menuPopupStart,
+    menuStart,
+    rowCollapsed,
+    rowCountChanged,
+    rowExpanded,
+    scrollPositionChanged,
+    scrolledToAnchor,
+    selectedChildrenChanged,
+    selectedTextChanged,
+    selectionChanged,
+    show,
+    textChanged,
+    textInserted,
+    textRemoved,
+    valueChanged
+  };
+
+  // Describes the purpose of an $(ref:automation.AutomationNode).
+  enum RoleType {
+    alertDialog,
+    alert,
+    annotation,
+    application,
+    article,
+    banner,
+    browser,
+    busyIndicator,
+    button,
+    buttonDropDown,
+    canvas,
+    cell,
+    checkBox,
+    client,
+    colorWell,
+    columnHeader,
+    column,
+    comboBox,
+    complementary,
+    contentInfo,
+    definition,
+    descriptionListDetail,
+    descriptionListTerm,
+    desktop,
+    dialog,
+    directory,
+    disclosureTriangle,
+    div,
+    document,
+    drawer,
+    editableText,
+    embeddedObject,
+    footer,
+    form,
+    grid,
+    group,
+    growArea,
+    heading,
+    helpTag,
+    horizontalRule,
+    iframe,
+    ignored,
+    imageMapLink,
+    imageMap,
+    image,
+    incrementor,
+    inlineTextBox,
+    labelText,
+    legend,
+    link,
+    listBoxOption,
+    listBox,
+    listItem,
+    listMarker,
+    list,
+    locationBar,
+    log,
+    main,
+    marquee,
+    mathElement,
+    math,
+    matte,
+    menuBar,
+    menuButton,
+    menuItem,
+    menuListOption,
+    menuListPopup,
+    menu,
+    navigation,
+    note,
+    outline,
+    pane,
+    paragraph,
+    popUpButton,
+    presentational,
+    progressIndicator,
+    radioButton,
+    radioGroup,
+    region,
+    rootWebArea,
+    rowHeader,
+    row,
+    rulerMarker,
+    ruler,
+    svgRoot,
+    scrollArea,
+    scrollBar,
+    seamlessWebArea,
+    search,
+    sheet,
+    slider,
+    sliderThumb,
+    spinButtonPart,
+    spinButton,
+    splitGroup,
+    splitter,
+    staticText,
+    status,
+    systemWide,
+    tabGroup,
+    tabList,
+    tabPanel,
+    tab,
+    tableHeaderContainer,
+    table,
+    textArea,
+    textField,
+    timer,
+    titleBar,
+    toggleButton,
+    toolbar,
+    treeGrid,
+    treeItem,
+    tree,
+    unknown,
+    tooltip,
+    valueIndicator,
+    webArea,
+    window
+  };
+
+  // Describes characteristics of an $(ref:automation.AutomationNode).
+  enum StateType {
+    busy,
+    checked,
+    collapsed,
+    default,
+    disabled,  // ui/views only

[aboxhall, 2014/06/17 15:04:18]

What happens to these comments when the doc is generated?

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

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

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

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

+    editable,  // ui/views only
+    enabled,   // content only
+    expanded,
+    focusable,
+    focused,
+    haspopup,
+    hovered,
+    indeterminate,
+    invisible,
+    linked,
+    multiselectable,
+    offscreen,
+    pressed,
+    protected,
+    readOnly,
+    required,
+    selectable,
+    selected,
+    vertical,
+    visited
+  };
+
   dictionary Rect {
     long left;
     long top;
     long width;
     long height;
   };
 
   // An event in the Automation tree.
-  [nocompile] dictionary AutomationEvent {
+  [nocompile, noinline_doc] dictionary AutomationEvent {

[aboxhall, 2014/06/17 15:04:18]

Why noinline_doc?

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

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

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

Oh! How annoying.

     // The $(ref:automation.AutomationNode) to which the event was targeted.
     AutomationNode target;
 
     // The type of the event.
-    DOMString type;
+    EventType type;
 
-    // Prevents all other event listeners from being triggered for this event
-    // dispatch.
+    // Prevent the further bubbling (or capturing) phases of this event. Note

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

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.

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

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

+    // any remaining listeners on $(ref:EventType.target) will be allowed to
+    // process this event.
     static void stopPropagation();
   };
 
   // A listener for events on an <code>AutomationNode</code>.
   callback AutomationListener = void(AutomationEvent event);
 
   // A single node in an Automation tree.
-  [nocompile] dictionary AutomationNode {
+  [nocompile, noinline_doc] dictionary AutomationNode {
     // The root node of the tree containing this AutomationNode.
     AutomationRootNode root;
 
     // Whether this AutomationNode is an AutomationRootNode.
     bool isRootNode;
 
     // Unique ID to identify this node.
     long id;
 
-    // The role of this node, e.g. button, static text etc.
-    DOMString role;
+    // The role of this node.
+    automation.RoleType role;
 
-    // The state of this node, e.g. {pressed": true, "inactive": true} etc.
+    // The $(ref:automation.StateType)s describing this node.
     object state;
 
     // The rendered location (as a bounding box) of this node within the frame.
-    Rect location;
+    automation.Rect location;
 
     // A collection of this node's other attributes.
-    // TODO(aboxhall): Create and use combined list of attributes from
-    // AXStringAttribute, AXIntAttribute etc.
     object? attributes;
 
     // The index of this node in its parent node's list of children. If this is
     // the root node, this will be undefined.
     long? indexInParent;
 
-    // Traversal.
-    static object[] children();
-    static object parent();
-    static object firstChild();
-    static object lastChild();
-    static object previousSibling();
-    static object nextSibling();
+    static AutomationNode[] children();
+    static AutomationNode parent();
+    static AutomationNode firstChild();
+    static AutomationNode lastChild();
+    static AutomationNode previousSibling();
+    static AutomationNode nextSibling();
 
-    // Actions.
+    // Do the default action based on this node's role (e.g. click a button).

[aboxhall, 2014/06/17 15:04:18]

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"

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

Done.

     static void doDefault();
+
+    // Places focus on this node.
     static void focus();
+
+    // Scrolls this node to make it visible.
     static void makeVisible();
+
+    // Sets selection within a text field.
     static void setSelection(long startIndex, long endIndex);
 
-    // Events.
+    // Adds a listener for the given event type and event phase.
     static void addEventListener(
-        DOMString eventType, AutomationListener listener, bool capture);
+        EventType eventType, AutomationListener listener, bool capture);
+
+    // Removes a listener for the given event type and event phase.
     static void removeEventListener(
-        DOMString eventType, AutomationListener listener, bool capture);
+        EventType eventType, AutomationListener listener, bool capture);
   };
 
   // The root node of the automation tree for a single frame or desktop.
   // This may be:
   // <ul>
   //   <li> The desktop
   //   <li> The top frame of a page
   //   <li> A frame or iframe within a page
   // </ul>
   // Thus, an <code>AutomationRootNode</code> may be a descendant of one or
   // more <code>AutomationRootNode</code>s, and in turn have one or more
   // <code>AutomationRootNode</code>s in its descendants. Thus, the
   // <code>root</code> property of the <code>AutomationRootNode</code> will be
   // the immediate parent <code>AutomationRootNode</code>, or <code>null</code>
   // if this is the top-level <code>AutomationRootNode</code>.
   //
   // Extends $(ref:automation.AutomationNode).
-  [nocompile] dictionary AutomationRootNode {
+  [nocompile, noinline_doc] dictionary AutomationRootNode {
+    // TODO(aboxhall/dtseng): implement loading. Kept separate to not include

[aboxhall, 2014/06/17 15:04:18]

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:36]

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]

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?

+    // in generated docs.
+
     // Whether this AutomationRootNode is loaded or not. If false, call load()
     // to get the contents.
-    // TODO(aboxhall/dtseng): implement.
     bool loaded;
 
     // Load the accessibility tree for this AutomationRootNode.
-    // TODO(aboxhall/dtseng): implement.
     static void load(RootCallback callback);
   };
 
   // Called when the <code>AutomationRootNode</code> for the page is available.
   callback RootCallback = void(AutomationRootNode rootNode);
 
   interface Functions {
     // Get the automation tree for the tab with the given tabId, or the current
     // tab if no tabID is given, enabling automation if necessary. Returns a
     // tree with a placeholder root node; listen for the "loadComplete" event to
     // get a notification that the tree has fully loaded (the previous root node
     // reference will stop working at or before this point).
     [nocompile] static void getTree(optional long tabId, RootCallback callback);
 
-    // Get the automation tree for the desktop.
+    // Get the automation tree for the whole desktop which consists of all on
+    // screen views. Note this API is currently only supported on Chrome OS.
     [nocompile] static void getDesktop(RootCallback callback);
   };
 };