Bug 748069 - Document UtteranceGenerator. r=surkov
authorEitan Isaacson <eitan@monotonous.org>
Mon, 07 May 2012 09:44:44 -0700
changeset 93351 bc7f3a9deba8d737c54369270a00fcb2b091cecc
parent 93350 1bb9382bcbd116ef0993d835cd62af39674c149e
child 93352 b58c6e5156d72bace8e3d5a8f74d8014cb39ff46
push id9092
push usereisaacson@mozilla.com
push dateMon, 07 May 2012 16:52:51 +0000
treeherdermozilla-inbound@b58c6e5156d7 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerssurkov
bugs748069
milestone15.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 748069 - Document UtteranceGenerator. r=surkov
accessible/src/jsat/AccessFu.jsm
accessible/src/jsat/UtteranceGenerator.jsm
--- a/accessible/src/jsat/AccessFu.jsm
+++ b/accessible/src/jsat/AccessFu.jsm
@@ -48,19 +48,18 @@ var AccessFu = {
     } catch (x) {
     }
 
     if (this.amINeeded(accessPref))
       this.enable();
   },
 
   /**
-   * Start the special AccessFu mode, this primarily means controlling the virtual
-   * cursor with arrow keys. Currently, on platforms other than Android this needs
-   * to be called explicitly.
+   * Start AccessFu mode, this primarily means controlling the virtual cursor
+   * with arrow keys.
    */
   enable: function enable() {
     dump('AccessFu enable');
     this.addPresenter(new VisualPresenter());
 
     // Implicitly add the Android presenter on Android.
     if (Services.appinfo.OS == 'Android')
       this.addPresenter(new AndroidPresenter());
--- a/accessible/src/jsat/UtteranceGenerator.jsm
+++ b/accessible/src/jsat/UtteranceGenerator.jsm
@@ -17,16 +17,32 @@ var gStringBundle = Cc['@mozilla.org/int
   getService(Ci.nsIStringBundleService).
   createBundle('chrome://global/locale/AccessFu.properties');
 
 var gAccRetrieval = Cc['@mozilla.org/accessibleRetrieval;1'].
   getService(Ci.nsIAccessibleRetrieval);
 
 var EXPORTED_SYMBOLS = ['UtteranceGenerator'];
 
+/**
+ * Generates speech utterances from objects, actions and state changes.
+ * An utterance is an array of strings.
+ *
+ * It should not be assumed that flattening an utterance array would create a
+ * gramatically correct sentence. For example, {@link genForObject} might
+ * return: ['graphic', 'Welcome to my home page'].
+ * Each string element in an utterance should be gramatically correct in itself.
+ * Another example from {@link genForObject}: ['list item 2 of 5', 'Alabama'].
+ *
+ * An utterance is ordered from the least to the most important. Speaking the
+ * last string usually makes sense, but speaking the first often won't.
+ * For example {@link genForAction} might return ['button', 'clicked'] for a
+ * clicked event. Speaking only 'clicked' makes sense. Speaking 'button' does
+ * not.
+ */
 var UtteranceGenerator = {
   gActionMap: {
     jump: 'jumpAction',
     press: 'pressAction',
     check: 'checkAction',
     uncheck: 'uncheckAction',
     select: 'selectAction',
     open: 'openAction',
@@ -34,34 +50,64 @@ var UtteranceGenerator = {
     switch: 'switchAction',
     click: 'clickAction',
     collapse: 'collapseAction',
     expand: 'expandAction',
     activate: 'activateAction',
     cycle: 'cycleAction'
   },
 
+
+  /**
+   * Generates an utterance for an object.
+   * @param {nsIAccessible} aAccessible accessible object to generate utterance
+   *    for.
+   * @param {boolean} aForceName include the object's name in the utterance
+   *    even if this object type does not usually have it's name uttered.
+   * @return {Array} Two string array. The first string describes the object
+   *    and its states. The second string is the object's name. Some object
+   *    types may have the description or name omitted, instead an empty string
+   *    is returned as a placeholder. Whether the object's description or it's role
+   *    is included is determined by {@link verbosityRoleMap}.
+   */
   genForObject: function(aAccessible, aForceName) {
     let roleString = gAccRetrieval.getStringRole(aAccessible.role);
 
     let func = this.objectUtteranceFunctions[roleString] ||
       this.objectUtteranceFunctions.defaultFunc;
 
     let flags = this.verbosityRoleMap[roleString] || 0;
 
     if (aForceName)
       flags |= INCLUDE_NAME;
 
     return func.apply(this, [aAccessible, roleString, flags]);
   },
 
+  /**
+   * Generates an utterance for an action performed.
+   * TODO: May become more verbose in the future.
+   * @param {nsIAccessible} aAccessible accessible object that the action was
+   *    invoked in.
+   * @param {string} aActionName the name of the action, one of the keys in
+   *    {@link gActionMap}.
+   * @return {Array} A one string array with the action.
+   */
   genForAction: function(aObject, aActionName) {
     return [gStringBundle.GetStringFromName(this.gActionMap[aActionName])];
   },
 
+  /**
+   * Generates an utterance for a tab state change.
+   * @param {nsIAccessible} aAccessible accessible object of the tab's attached
+   *    document.
+   * @param {string} aTabState the tab state name, see
+   *    {@link Presenter.tabStateChanged}.
+   * @return {Array} The tab state utterace.
+   */
   genForTabStateChange: function (aObject, aTabState) {
     switch (aTabState) {
       case 'newtab':
         return [gStringBundle.GetStringFromName('tabNew')];
       case 'loading':
         return [gStringBundle.GetStringFromName('tabLoading')];
       case 'loaded':
         return [aObject.name || '',