documentation. fixes #21

svg_rendering/page/js-gen/README.md

@@ -34,11 +34,6 @@ The rendering library relies on a proprietary text markup format. This can be ge
 
 `svg-utils.js` SVG utility functions
 
-### Legacy wrappers
-
-
-`materialunit.js` Handle archival objects (TODO: check if used and remove)
-
 
 ### Standoff annotation handling 
 
@@ -55,9 +50,9 @@ The rendering library relies on a proprietary text markup format. This can be ge
 
 `transcript-adhoc-tree.js` Initialize layout objects from document tree
 
-`transcript-configuration-faust.js` Parameters for transcript layout
+`transcript-configuration-faust.js` Configure parameters for transcript layout
 
 `transcript-generation.js` Entry point for transcript generation
 
-`transcript-svg.js` Augment the abstract classes in `transcript.js` to do the layout with an SVG terminal 
+`transcript-svg.js` Augment the abstract classes in `transcript.js` to do the layout with an SVG 'terminal' 
 

svg_rendering/page/js-gen/adhoc-tree.js

@@ -17,6 +17,10 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file Build a tree from the standoff annotations from `text-annotaion.js`
+ */
+
 if (window.Faust === undefined) {
     window.Faust = {};
 }

svg_rendering/page/js-gen/faust.js

@@ -17,10 +17,20 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file General utility functions. 
+ */
+
 if (window.Faust === undefined) {
     window.Faust = {};
 }
 (function (Faust) {
+
+    /**
+     * Encode UTF-8 characters in a URI
+     * @param {string} path
+     * @returns {string}
+     */
     Faust.encodePath = function (path) {
         var encoded = "";
         var pathComponents = path.split("/");
@@ -29,6 +39,12 @@ if (window.Faust === undefined) {
         return encoded;
     };
 
+    /**
+     * Represents a Faust URI with the scheme "faust://"
+     * @param uri
+     * @constructor
+     */
+
     Faust.URI = function (uri) {
         this.components = uri.match(/^faust:\/\/([^\/]+)\/(.*)/);
     };
@@ -39,12 +55,6 @@ if (window.Faust === undefined) {
         }
     };
 
-    /* REMOVE
-     Faust.YUI = function() {
-     return YUI();
-     };
-     */
-
     Faust.io = function (uri, callback, reviver) {
         var xhr = new XMLHttpRequest();
         xhr.open("GET", uri, true);
@@ -71,38 +81,4 @@ if (window.Faust === undefined) {
         }
         xhr.send(null);
     };
-    /* REMOVE
-     Faust.io = function(uri, callback, reviver) {
-     Faust.YUI().use("io", "json", function(Y) {
-     Y.io(Faust.contextPath + "/" + uri, {
-     method: "GET",
-     xdr: { responseXML: false },
-     headers: { "Accept": "application/json" },
-     on: {
-     success: function(id, o, a) {
-     callback(Y.JSON.parse(o.responseText, reviver));
-     },
-     failure: function(id, o, a) {
-     Y.log("ERROR " + id + " " + a, "info", "Faust") }
-     }
-     });
-     });
-     };
-     */
-    /* REMOVE
-     Faust.xml = function(uri, callback) {
-     Faust.YUI().use("io", function(Y) {
-     Y.io(Faust.contextPath + "/" + uri, {
-     method: "GET",
-     on: {
-     success: function(id, o, a) {
-     callback(o.responseXML);
-     },
-     failure: function(id, o, a) {
-     Y.log("ERROR " + id + " " + a, "info", "Faust") }
-     }
-     });
-     });
-     };
-     */
 })(Faust);

svg_rendering/page/js-gen/loadwebfonts.js

@@ -17,6 +17,10 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file Wrap the Google web font loader
+ */
+
 if (window.Faust === undefined) {
     window.Faust = {};
 }

svg_rendering/page/js-gen/svg-utils.js

@@ -17,6 +17,10 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file SVG utility functions
+ */
+
 if (window.SvgUtils === undefined) {
     window.SvgUtils = {};
 }
@@ -26,6 +30,12 @@ if (window.SvgUtils === undefined) {
 
     var SVG_NS = "http://www.w3.org/2000/svg";
 
+    /**
+     * Decode arbitrary data coded in class values in the form of a class "keyvalue"
+     * @param classValue
+     * @param key The key, the be prefix of a class "keyvalue"
+     * @returns {string} the postfix following the key in a class "keyvalue"
+     */
     function decodeClassValue(classValue, key) {
         var start = classValue.indexOf(key);
         if (start < 0) {
@@ -43,6 +53,11 @@ if (window.SvgUtils === undefined) {
         };
     }
 
+    /**
+     * Create an SVG element
+     * @param name
+     * @returns {Element} A new SVG element
+     */
     function svgElement(name) {
         return document.createElementNS(SVG_NS, name);
     }
@@ -97,6 +112,9 @@ if (window.SvgUtils === undefined) {
 
     // An implementation of getScreenBBox, by Antoine Quint, modiefied by Moritz Wissenbach
     // http://the.fuchsia-design.com/2006/12/getting-svg-elementss-full-bounding-box.html
+    /**
+     * Return the bounding box in screen coordinates.
+     */
     function getScreenBBox(element, svgRoot) {
 
         // macro to create an SVGPoint object
@@ -168,7 +186,6 @@ if (window.SvgUtils === undefined) {
     /**
      * Safely get and return the bounding box of element as seen from its local coordinate system.
      */
-
     function localBoundingBox(element) {
 
         // Firefox will throw an exception when calling getBBox() on an element with display: none

svg_rendering/page/js-gen/text-annotation.js

@@ -17,6 +17,10 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file Parse standoff markup. See Text.create() documentation for a description of the markup format.
+ */
+
 if (window.Faust === undefined) {
     window.Faust = {};
 }
@@ -27,10 +31,12 @@ if (window.Faust === undefined) {
         this.start = start;
         this.end = end;
     };
+
     var Name = function (namespace, localName) {
         this.namespace = namespace;
         this.localName = localName;
     };
+
     var Text = function (id, type, contentLength, range, content) {
         this.id = id;
         this.type = type;
@@ -190,6 +196,53 @@ if (window.Faust === undefined) {
             }
         }
     }, {
+        /**
+         * Constructs a queryable object of standoff-annotated text.
+         * @param data Text content and annotations. See provided example for details on the format.
+         * @returns The queryable annotated Text object
+         * @example <caption>An example for the JSON format of the data parameter. "textContent" contains the plain text.
+         *   "names" is a map of shorthands for namespace-qualified names, to be referenced from the annotation's "n"
+         *   field. An annotation further contains a "t" field (for "target") which has the format
+         *   [startChar, endChar, textId]. An annotation further has a unique "id" and a field "d" ("data") for arbitrary
+         *   key-value pairs. The top level "text" field has the same content model as an "annotation", but for this use
+         *   case its only relevant field is "id", which is referenced in all the annotations (as the text is the
+         *   annotations target).</caption>
+         *   <pre><code>
+         *   {
+         *     "text":{
+         *       "n":100,
+         *       "t":[[0, 14, 200]],
+         *       "d":{},
+         *       "id":0
+         *     },
+         *     "textContent":"Roses are red.",
+         *     "names":{
+         *       "10":[
+         *         "http://www.examplenamespace.org/ns",
+         *         "word"
+         *       ],
+         *       "11":[
+         *         "http://www.examplenamespace.org/ns",
+         *         "punctuation"
+         *       ],
+         *     },
+         *     "annotations":[
+         *       {
+         *         "n":10,
+         *         "t":[[0, 5, 0]],
+         *         "d":{"key1": "value1", "key2": "value2"},
+         *         "id":1
+         *       },
+         *       {
+         *         "n":11,
+         *         "t":[[13, 14, 0]],
+         *         "d":{},
+         *         "id":2
+         *       },
+         *     ]
+         *   }
+         *   </code></pre>
+         */
         create: function (data) {
             var text = new Text(data.text.id, data.text.t, data.text.l, data.textRange, data.textContent), names = {};
             Object.keys(data.names).forEach(function (name) {

svg_rendering/page/js-gen/text-index.js

@@ -17,6 +17,10 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file Standoff annotation index for fast lookup
+ */
+
 if (window.Faust === undefined) {
     window.Faust = {};
 }

svg_rendering/page/js-gen/transcript-adhoc-tree.js

@@ -17,6 +17,10 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file Initialize layout objects from document tree
+ */
+
 if (window.FaustTranscript === undefined) {
     window.FaustTranscript = {};
 }
@@ -27,8 +31,10 @@ if (window.Faust === undefined) {
 (function (Faust) {
 
     var TranscriptLayout = {
-        // Text factory; the current model only delivers text nodes, some additional elements (gaps, insertion marks) need
-        // to be delivered to know their tree context (hands...) for visualisation
+        /**
+         * Text factory; the current model only delivers text nodes, some additional elements (gaps, insertion marks)
+         * need to be delivered to know their tree context (hands...) for visualisation
+         */
         createText: function (content, start, end, text, layoutState) {
             if (content.length < 1) {
                 throw "Cannot create empty text!";
@@ -63,11 +69,13 @@ if (window.Faust === undefined) {
 })(Faust);
 
 
-///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-
 
 (function (FaustTranscript) {
 
+    /**
+     * Initialize a ViewComponent tree from an AdhocTree
+     * @constructor
+     */
     var TranscriptAdhocTree = function () {
         this.mainZone = null;
         this.idMap = {};
@@ -76,6 +84,14 @@ if (window.Faust === undefined) {
 
     Y.extend(TranscriptAdhocTree, Object, {
 
+        /**
+         * Walk an AdhocTree and construct a tree of ViewComponents
+         * @param {ViewComponent} parent
+         * @param {AnnotationNode} node
+         * @param {Text} text The standoff-annotated text
+         * @param layoutState An object that stores variables global w.r.t. one layout process
+         * @returns {*}
+         */
         buildVC: function (parent, node, text, layoutState) {
 
             if (node == null) {

svg_rendering/page/js-gen/transcript-configuration-faust.js

@@ -17,6 +17,9 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file Configure parameters for transcript layout
+ */
 
 if (window.Faust === undefined) {
     window.Faust = {};
@@ -44,9 +47,10 @@ if (window.Faust === undefined) {
         return classes;
     }
 
-    // A configuration defines how markup is rendered by providing handler
-    // functions in Y.Faust.TranscriptConfiguration.
-
+    /**
+     * A configuration defines how markup is rendered by providing handler
+     * functions in Y.Faust.TranscriptConfiguration.
+     */
     Faust.TranscriptConfiguration = {
         // should overlapping stuff be rendered on top of each other?
         // overlay : "overlay",

svg_rendering/page/js-gen/transcript-generation.js

@@ -17,6 +17,10 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file Entry point for transcript generation
+ */
+
 var transcriptGeneration = (function () {
     "use strict";
 

svg_rendering/page/js-gen/transcript-svg.js

@@ -17,14 +17,19 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file Augment the abstract classes in `transcript.js` to do the layout with an SVG 'terminal'. See 'transcript.js'
+ * for a description of the classes and functions that are overwritten here.
+ */
+
 if (window.FaustTranscript === undefined) {
     window.FaustTranscript = {};
 }
 
 (function (FaustTranscript) {
 
     var SVG_NS = "http://www.w3.org/2000/svg";
-//  var DRAG_NS = "http://www.codedread.com/dragsvg";
+    //  var DRAG_NS = "http://www.codedread.com/dragsvg";
 
     // Implementation of View Components. Keep in sync with transcript.js.
     // These components are based on SVG. The model is only