Bug 1447977 - Move evaluate module API docs to RST. r=automatedtester
authorAndreas Tolfsen <ato@sny.no>
Fri, 06 Jul 2018 16:36:19 +0100
changeset 425708 dccb4ac6468a39d0266039d5c0ad0ca9cbe2c462
parent 425707 b2cd0e01b6556147c4b0c51960f668ec71580d95
child 425709 cbb958819d32f25d41d0e6fe61105d57a882b3eb
push id66200
push useratolfsen@mozilla.com
push dateTue, 10 Jul 2018 21:22:45 +0000
treeherderautoland@b4cd5a640564 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersautomatedtester
bugs1447977
milestone63.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 1447977 - Move evaluate module API docs to RST. r=automatedtester MozReview-Commit-ID: I5Pj8EsNyFc
testing/marionette/evaluate.js
--- a/testing/marionette/evaluate.js
+++ b/testing/marionette/evaluate.js
@@ -145,29 +145,29 @@ evaluate.sandbox = function(sb, script, 
  * looking them up in the seen element store.
  *
  * @param {Object} obj
  *     Arbitrary object containing web elements.
  * @param {element.Store=} seenEls
  *     Known element store to look up web elements from.  If undefined,
  *     the web element references are returned instead.
  * @param {WindowProxy=} window
- *     Current browsing context, if <var>seenEls</var> is provided.
+ *     Current browsing context, if `seenEls` is provided.
  *
  * @return {Object}
- *     Same object as provided by <var>obj</var> with the web elements
+ *     Same object as provided by `obj` with the web elements
  *     replaced by DOM elements.
  *
  * @throws {NoSuchElementError}
- *     If <var>seenEls</var> is given and the web element reference
- *     has not been seen before.
+ *     If `seenEls` is given and the web element reference has not
+ *     been seen before.
  * @throws {StaleElementReferenceError}
- *     If <var>seenEls</var> is given and the element has gone stale,
- *     indicating it is no longer attached to the DOM, or its node
- *     document is no longer the active document.
+ *     If `seenEls` is given and the element has gone stale, indicating
+ *     it is no longer attached to the DOM, or its node document
+ *     is no longer the active document.
  */
 evaluate.fromJSON = function(obj, seenEls = undefined, window = undefined) {
   switch (typeof obj) {
     case "boolean":
     case "number":
     case "string":
     default:
       return obj;
@@ -199,50 +199,39 @@ evaluate.fromJSON = function(obj, seenEl
 };
 
 /**
  * Marshal arbitrary objects to JSON-safe primitives that can be
  * transported over the Marionette protocol.
  *
  * The marshaling rules are as follows:
  *
- * <ul>
- *
- * <li>
- * Primitives are returned as is.
+ * - Primitives are returned as is.
  *
- * <li>
- * Collections, such as <code>Array</code>, <code>NodeList</code>,
- * <code>HTMLCollection</code> et al. are expanded to arrays and
- * then recursed.
+ * - Collections, such as `Array<`, `NodeList`, `HTMLCollection`
+ *   et al. are expanded to arrays and then recursed.
  *
- * <li>
- * Elements that are not known web elements are added to the
- * <var>seenEls</var> element store.  Once known, the elements'
- * associated web element representation is returned.
+ * - Elements that are not known web elements are added to the
+ *   `seenEls` element store.  Once known, the elements' associated
+ *   web element representation is returned.
  *
- * <li>
- * Objects with custom JSON representations, i.e. if they have a
- * callable <code>toJSON</code> function, are returned verbatim.
- * This means their internal integrity <em>are not</em> checked.
- * Be careful.
+ * - Objects with custom JSON representations, i.e. if they have
+ *   a callable `toJSON` function, are returned verbatim.  This means
+ *   their internal integrity _are not_ checked.  Be careful.
  *
- * <li>
- * Other arbitrary objects are first tested for cyclic references
- * and then recursed into.
- *
- * </ul>
+ * -  Other arbitrary objects are first tested for cyclic references
+ *    and then recursed into.
  *
  * @param {Object} obj
  *     Object to be marshaled.
  * @param {element.Store} seenEls
  *     Element store to use for lookup of web element references.
  *
  * @return {Object}
- *     Same object as provided by <var>obj</var> with the elements
+ *     Same object as provided by `obj` with the elements
  *     replaced by web elements.
  *
  * @throws {JavaScriptError}
  *     If an object contains cyclic references.
  */
 evaluate.toJSON = function(obj, seenEls) {
   const t = Object.prototype.toString.call(obj);
 
@@ -290,19 +279,19 @@ evaluate.toJSON = function(obj, seenEls)
         throw e;
       }
     }
   }
   return rv;
 };
 
 /**
- * Cu.isDeadWrapper does not return true for a dead sandbox that was
- * assosciated with and extension popup. This provides a way to still
- * test for a dead object.
+ * `Cu.isDeadWrapper` does not return true for a dead sandbox that
+ * was assosciated with and extension popup.  This provides a way to
+ * still test for a dead object.
  *
  * @param {Object} obj
  *     A potentially dead object.
  * @param {string} prop
  *     Name of a property on the object.
  *
  * @returns {boolean}
  *     True if <var>obj</var> is dead, false otherwise.
@@ -321,33 +310,32 @@ evaluate.isDead = function(obj, prop) {
 
 this.sandbox = {};
 
 /**
  * Provides a safe way to take an object defined in a privileged scope and
  * create a structured clone of it in a less-privileged scope.  It returns
  * a reference to the clone.
  *
- * Unlike for {@link Components.utils.cloneInto}, <var>obj</var> may
- * contain functions and DOM elemnets.
+ * Unlike for {@link Components.utils.cloneInto}, `obj` may contain
+ * functions and DOM elements.
  */
 sandbox.cloneInto = function(obj, sb) {
   return Cu.cloneInto(obj, sb, {cloneFunctions: true, wrapReflectors: true});
 };
 
 /**
- * Augment given sandbox by an adapter that has an <code>exports</code>
- * map property, or a normal map, of function names and function
- * references.
+ * Augment given sandbox by an adapter that has an `exports` map
+ * property, or a normal map, of function names and function references.
  *
  * @param {Sandbox} sb
  *     The sandbox to augment.
  * @param {Object} adapter
- *     Object that holds an <code>exports</code> property, or a map, of
- *     function names and function references.
+ *     Object that holds an `exports` property, or a map, of function
+ *     names and function references.
  *
  * @return {Sandbox}
  *     The augmented sandbox.
  */
 sandbox.augment = function(sb, adapter) {
   function* entries(obj) {
     for (let key of Object.keys(obj)) {
       yield [key, obj[key]];