Rename doc template from apidoc to api

buildcfg/jsdoc/api/plugins/api.js

@@ -0,0 +1,130 @@
+/**
+ * Define an @api tag
+ */
+var conf = env.conf.stability;
+var defaultLevels = ["deprecated","experimental","unstable","stable","frozen","locked"];
+var levels = conf.levels || defaultLevels;
+var util = require('util');
+exports.defineTags = function(dictionary) {
+  dictionary.defineTag('api', {
+    mustHaveValue: false,
+    canHaveType: false,
+    canHaveName: false,
+    onTagged: function(doclet, tag) {
+      var level = tag.text || "experimental";
+      if (levels.indexOf(level) >= 0) {
+        doclet.stability = level;
+      } else {
+        var errorText = util.format('Invalid stability level (%s) in %s line %s', tag.text, doclet.meta.filename, doclet.meta.lineno);
+        require('jsdoc/util/error').handle( new Error(errorText) );
+      }
+    }
+  });
+};
+
+
+
+/*
+ * Based on @stability annotations, and assuming that items with no @stability
+ * annotation should not be documented, this plugin removes undocumented symbols
+ * from the documentation.
+ */
+
+function hasApiMembers(doclet) {
+  return doclet.longname.split('#')[0] == this.longname;
+}
+
+function includeAugments(doclet) {
+  var augments = doclet.augments;
+  if (augments) {
+    var cls;
+    for (var i = augments.length - 1; i >= 0; --i) {
+      cls = classes[augments[i]];
+      if (cls) {
+        includeAugments(cls);
+        if (cls.fires) {
+          if (!doclet.fires) {
+            doclet.fires = [];
+          }
+          cls.fires.forEach(function(f) {
+            if (doclet.fires.indexOf(f) == -1) {
+              doclet.fires.push(f);
+            }
+          });
+        }
+        if (cls.observables) {
+          if (!doclet.observables) {
+            doclet.observables = [];
+          }
+          cls.observables.forEach(function(f) {
+            if (doclet.observables.indexOf(f) == -1) {
+              doclet.observables.push(f);
+            }
+          });
+        }
+        if (cls.longname.indexOf('oli.') !== 0) {
+          cls._hideConstructor = true;
+          delete cls.undocumented;
+        }
+      }
+    }
+  }
+}
+
+var api = [];
+var classes = {};
+
+exports.handlers = {
+
+  newDoclet: function(e) {
+    var doclet = e.doclet;
+    // Keep track of api items - needed in parseComplete to determine classes
+    // with api members.
+    if (doclet.stability) {
+      api.push(doclet);
+    }
+    // Mark explicity defined namespaces - needed in parseComplete to keep
+    // namespaces that we need as containers for api items.
+    if (/.*\.jsdoc$/.test(doclet.meta.filename) && doclet.kind == 'namespace') {
+      doclet.namespace_ = true;
+    }
+    if (doclet.kind == 'class') {
+      classes[doclet.longname] = doclet;
+    }
+  },
+
+  parseComplete: function(e) {
+    var doclets = e.doclets;
+    for (var i = doclets.length - 1; i >= 0; --i) {
+      var doclet = doclets[i];
+      if (doclet.stability || doclet.namespace_) {
+        if (doclet.kind == 'class') {
+          includeAugments(doclet);
+        }
+        if (doclet.fires) {
+          doclet.fires.sort(function(a, b) {
+            return a.split(/#?event:/)[1] < b.split(/#?event:/)[1] ? -1 : 1;
+          });
+        }
+        if (doclet.observables) {
+          doclet.observables.sort(function(a, b) {
+            return a.name < b.name ? -1 : 1;
+          });
+        }
+        // Always document namespaces and items with stability annotation
+        continue;
+      }
+      if (doclet.kind == 'class' && api.some(hasApiMembers, doclet)) {
+        // Mark undocumented classes with documented members as unexported.
+        // This is used in ../template/tmpl/container.tmpl to hide the
+        // constructor from the docs.
+        doclet._hideConstructor = true;
+        includeAugments(doclet);
+      } else if (!doclet._hideConstructor) {
+        // Remove all other undocumented symbols
+        doclet.undocumented = true;
+      }
+    }
+  }
+
+};

buildcfg/jsdoc/api/plugins/events.js

@@ -0,0 +1,43 @@
+var events = {};
+var classes = {};
+
+exports.handlers = {
+
+  newDoclet: function(e) {
+    var doclet = e.doclet;
+    var cls;
+    if (doclet.kind == 'event') {
+      cls = doclet.longname.split('#')[0];
+      if (!(cls in events)) {
+        events[cls] = [];
+      }
+      events[cls].push(doclet.longname);
+    } else if (doclet.kind == 'class') {
+      classes[doclet.longname] = doclet;
+    }
+  },
+
+  parseComplete: function(e) {
+    var doclets = e.doclets;
+    var doclet, i, ii, j, jj, event, fires;
+    for (i = 0, ii = doclets.length - 1; i < ii; ++i) {
+      doclet = doclets[i];
+      if (doclet.fires) {
+        if (doclet.kind == 'class') {
+          fires = [];
+          for (j = 0, jj = doclet.fires.length; j < jj; ++j) {
+            event = doclet.fires[j].replace('event:', '');
+            if (events[event]) {
+              fires.push.apply(fires, events[event]);            
+            } else {
+              fires.push(doclet.fires[j]);
+            }
+          }
+          doclet.fires = fires;
+        }
+      }
+    }
+  }
+
+};
+

buildcfg/jsdoc/api/plugins/inheritdoc.js

@@ -0,0 +1,109 @@
+/*
+ * This is a hack to prevent inheritDoc tags from entirely removing
+ * documentation of the method that inherits the documentation.
+ *
+ * TODO: Remove this hack when https://github.com/jsdoc3/jsdoc/issues/53
+ * is addressed.
+ */
+
+
+exports.defineTags = function(dictionary) {
+  dictionary.defineTag('inheritDoc', {
+    mustHaveValue: false,
+    canHaveType: false,
+    canHaveName: false,
+    onTagged: function(doclet, tag) {
+      doclet.inheritdoc = true;
+    }
+  });
+};
+
+
+var lookup = {};
+var incompleteByClass = {};
+var keepKeys = ['comment', 'meta', 'name', 'memberof', 'longname', 'augment',
+    'stability'];
+
+exports.handlers = {
+
+  newDoclet: function(e) {
+    var doclet = e.doclet;
+    var incompletes;
+    if (!(doclet.longname in lookup)) {
+      lookup[doclet.longname] = [];
+    }
+    lookup[doclet.longname].push(doclet);
+    if (doclet.inheritdoc) {
+      if (!(doclet.memberof in incompleteByClass)) {
+        incompleteByClass[doclet.memberof] = [];
+      }
+      incompletes = incompleteByClass[doclet.memberof];
+      if (incompletes.indexOf(doclet.name) == -1) {
+        incompletes.push(doclet.name);
+      }
+    }
+  },
+
+  parseComplete: function(e) {
+    var ancestors, candidate, candidates, doclet, i, j, k, l, key;
+    var incompleteDoclet, stability, incomplete, incompletes;
+    var doclets = e.doclets;
+    for (i = doclets.length - 1; i >= 0; --i) {
+      doclet = doclets[i];
+      if (doclet.augments) {
+        ancestors = [].concat(doclet.augments);
+      }
+      incompletes = incompleteByClass[doclet.longname];
+      if (ancestors && incompletes) {
+        // collect ancestors from the whole hierarchy
+        for (j = 0; j < ancestors.length; ++j) {
+          candidates = lookup[ancestors[j]];
+          if (candidates) {
+            for (k = candidates.length - 1; k >= 0; --k) {
+              candidate = candidates[k];
+              if (candidate.augments) {
+                ancestors = ancestors.concat(candidate.augments);
+              }
+            }
+          }
+        }
+        // walk through all inheritDoc members
+        for (j = incompletes.length - 1; j >= 0; --j) {
+          incomplete = incompletes[j];
+          candidates = lookup[doclet.longname + '#' + incomplete];
+          if (candidates) {
+            // get the incomplete doclet that needs to be augmented
+            for (k = candidates.length - 1; k >= 0; --k) {
+              incompleteDoclet = candidates[k];
+              if (incompleteDoclet.inheritdoc) {
+                break;
+              }
+            }
+          }
+          // find the documented ancestor
+          for (k = ancestors.length - 1; k >= 0; --k) {
+            candidates = lookup[ancestors[k] + '#' + incomplete];
+            if (candidates) {
+              for (l = candidates.length - 1; l >= 0; --l) {
+                candidate = candidates[l];
+                if (candidate && !candidate.inheritdoc) {
+                  stability = candidate.stability || incompleteDoclet.stability;
+                  if (stability) {
+                    incompleteDoclet.stability = stability;
+                    for (key in candidate) {
+                      if (candidate.hasOwnProperty(key) &&
+                          keepKeys.indexOf(key) == -1) {
+                        incompleteDoclet[key] = candidate[key];
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+};

buildcfg/jsdoc/api/plugins/interface.js

@@ -0,0 +1,25 @@
+exports.defineTags = function(dictionary) {
+
+  var classTag = dictionary.lookUp('class');
+  dictionary.defineTag('interface', {
+    mustHaveValue: false,
+    onTagged: function(doclet, tag) {
+      classTag.onTagged.apply(this, arguments);
+      doclet.interface = true;
+    }
+  });
+
+  var augmentsTag = dictionary.lookUp('augments');
+  dictionary.defineTag('implements', {
+    mustHaveValue: true,
+    onTagged: function(doclet, tag) {
+      tag.value = tag.value.match(/^\{?([^\}]*)\}?$/)[1];
+      augmentsTag.onTagged.apply(this, arguments);
+      if (!doclet.implements) {
+        doclet.implements = [];
+      }
+      doclet.implements.push(tag.value);
+    }
+  });
+
+};

buildcfg/jsdoc/api/plugins/observable.js

@@ -0,0 +1,66 @@
+var classes = {};
+var observables = {};
+
+exports.handlers = {
+
+  newDoclet: function(e) {
+    var doclet = e.doclet;
+    if (doclet.kind == 'class') {
+      classes[doclet.longname] = doclet;
+    }
+  },
+
+  parseComplete: function(e) {
+    var doclets = e.doclets;
+    var cls, doclet, event, i, ii, observable;
+    for (i = 0, ii = doclets.length - 1; i < ii; ++i) {
+      doclet = doclets[i];
+      cls = classes[doclet.longname.split('#')[0]];
+      if (typeof doclet.observable == 'string' && cls) {
+        var name = doclet.name.replace(/^[sg]et/, '');
+        name = name.substr(0, 1).toLowerCase() + name.substr(1);
+        var key = doclet.longname.split('#')[0] + '#' + name;
+        doclet.observable = key;
+        if (!observables[key]) {
+          observables[key] = {};
+        }
+        observable = observables[key];
+        observable.name = name;
+        observable.readonly = typeof observable.readonly == 'boolean' ?
+            observable.readonly : true;
+        if (doclet.name.indexOf('get') === 0) {
+          observable.type = doclet.returns[0].type;
+          observable.description = doclet.returns[0].description;
+        } else if (doclet.name.indexOf('set') === 0) {
+          observable.readonly = false;
+        }
+        if (!cls.observables) {
+          cls.observables = [];
+        }
+        observable = observables[doclet.observable];
+        if (cls.observables.indexOf(observable) == -1) {
+          cls.observables.push(observable);
+        }
+        if (!cls.fires) {
+          cls.fires = [];
+        }
+        event = 'ol.ObjectEvent#event:change:' + name.toLowerCase();
+        if (cls.fires.indexOf(event) == -1) {
+          cls.fires.push(event);
+        }
+      }
+    }
+  }
+
+};
+
+exports.defineTags = function(dictionary) {
+  dictionary.defineTag('observable', {
+    mustNotHaveValue: true,
+    canHaveType: false,
+    canHaveName: false,
+    onTagged: function(doclet, tag) {
+      doclet.observable = '';
+    }
+  });
+};

buildcfg/jsdoc/api/plugins/typedefs.js

@@ -0,0 +1,63 @@
+/*
+ * Converts olx.js @type annotations into properties of the previous @typedef.
+ * Changes @enum annotations into @typedef.
+ */
+
+var lastOlxTypedef = null;
+var olxTypes = {};
+
+function addSubparams(params) {
+  for (var j = 0, jj = params.length; j < jj; ++j) {
+    var param = params[j];
+    var types = param.type.names;
+    for (var k = 0, kk = types.length; k < kk; ++k) {
+      var name = types[k];
+      if (name in olxTypes) {
+        param.subparams = olxTypes[name];
+        // TODO addSubparams(param.subparams);
+        // TODO Do we need to support multiple object literal types per
+        // param?
+        break;
+      }
+    }
+  }
+}
+
+exports.handlers = {
+
+  newDoclet: function(e) {
+    var doclet = e.doclet;
+    if (doclet.meta.filename == 'olx.js') {
+      // do nothing if not marked @api
+      if (!doclet.stability) {
+        return;
+      }
+      if (doclet.kind == 'typedef') {
+        lastOlxTypedef = doclet;
+        olxTypes[doclet.longname] = [];
+        doclet.properties = [];
+      } else if (lastOlxTypedef && doclet.memberof == lastOlxTypedef.longname) {
+        lastOlxTypedef.properties.push(doclet);
+        olxTypes[lastOlxTypedef.longname].push(doclet);
+      } else {
+        lastOlxTypedef = null;
+      }
+    } else if (doclet.isEnum) {
+      // We never export enums, so we document them like typedefs
+      doclet.kind = 'typedef';
+      delete doclet.isEnum;
+    }
+  },
+
+  parseComplete: function(e) {
+    var doclets = e.doclets;
+    for (var i = doclets.length - 1; i >= 0; --i) {
+      var doclet = doclets[i];
+      var params = doclet.params;
+      if (params) {
+        addSubparams(params);
+      }
+    }
+  }
+
+};