Bug 1447977 - Move evaluate module API docs to RST. r=automatedtester a=test-only
authorAndreas Tolfsen <ato@sny.no>
Fri, 06 Jul 2018 16:36:19 +0100
changeset 478125 332084df66518b9065ce7f4eebbda8ae5db41338
parent 478124 39837622272f4606a18c3900d0f4c9d7e4fb1137
child 478126 43f6112e957876670aa24461d6d751a8de5b3cfb
push id9539
push userarchaeopteryx@coole-files.de
push dateThu, 26 Jul 2018 08:07:25 +0000
treeherdermozilla-beta@20c023fb254c [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersautomatedtester, test-only
bugs1447977
milestone62.0
Bug 1447977 - Move evaluate module API docs to RST. r=automatedtester a=test-only MozReview-Commit-ID: I5Pj8EsNyFc
testing/marionette/evaluate.js
--- a/testing/marionette/evaluate.js
+++ b/testing/marionette/evaluate.js
@@ -156,29 +156,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;
@@ -210,50 +210,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);
 
@@ -301,19 +290,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.
@@ -332,33 +321,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]];