Merge pull request openlayers#527 from ahocevar/jsdoc-filtered

Only document the exported API, not every symbol. r=@elemoint

build.py

@@ -572,6 +572,7 @@ def gh_pages(t):
 
 
 @target('build/jsdoc-%(BRANCH)s-timestamp' % vars(variables), 'host-resources',
+        'build/src/external/src/exports.js', 'build/src/external/src/types.js',
         SRC, SHADER_SRC, ifind('doc/template'))
 def jsdoc_BRANCH_timestamp(t):
     t.run('%(JSDOC)s', '-c', 'doc/conf.json', 'src', 'doc/index.md',

doc/conf.json

@@ -11,7 +11,11 @@
         "includePattern": ".+\\.js(doc)?$",
         "excludePattern": "(^|\\/|\\\\)_"
     },
-    "plugins": [ "plugins/markdown", "doc/plugins/inheritdoc" ],
+    "plugins": [
+        "plugins/markdown",
+        "doc/plugins/inheritdoc",
+        "doc/plugins/exports"
+    ],
     "markdown": {
         "parser": "gfm"
     },

doc/plugins/exports.js

@@ -0,0 +1,94 @@
+/*
+ * This plugin parses goog.exportSymbol and goog.exportProperty calls to build
+ * a list of API symbols and properties. Everything else is marked undocumented,
+ * which will remove it from the docs.
+ */
+
+var api = [];
+
+function collectExports(source) {
+  var i, ii, symbol, property;
+  var syms = source.match(/goog\.exportSymbol\([^\)]*\)/g);
+  if (syms) {
+    i = 0; ii = syms.length;
+    for (; i < ii; ++i) {
+      symbol = syms[i].match(/'([^']*)'/)[1];
+      api.push(symbol);
+    }
+  }
+  var props = source.match(/goog\.exportProperty\([^\)]*\)/g);
+  if (props) {
+    i = 0; ii = props.length;
+    for (; i < ii; ++i) {
+      property = props[i].match(/[^,]*,[^,]*,\r?\n? *([^\)]*)\)/)[1]
+          .replace('.prototype.', '#');
+      api.push(property);
+    }
+  }
+}
+
+var encoding = env.conf.encoding || 'utf8';
+var fs = require('jsdoc/fs');
+collectExports(fs.readFileSync('build/src/external/src/exports.js', encoding));
+collectExports(fs.readFileSync('build/src/external/src/types.js', encoding));
+
+
+exports.handlers = {
+
+  beforeParse: function(e) {
+    if (/\.js$/.test(e.filename)) {
+      collectExports(e.source);
+    }
+  },
+
+  newDoclet: function(e) {
+    if (api.indexOf(e.doclet.longname) > -1) {
+      // Add params of API symbols to the API
+      var names, name;
+      var params = e.doclet.params;
+      if (params) {
+        for (var i = 0, ii = params.length; i < ii; ++i) {
+          names = params[i].type.names;
+          if (names) {
+            for (var j = 0, jj=names.length; j < jj; ++j) {
+              name = names[j];
+              if (api.indexOf(name) === -1) {
+                api.push(name);
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+};
+
+
+function filter(e) {
+  if (e.doclet) {
+    var fqn = e.doclet.longname;
+    if (fqn) {
+      e.doclet.undocumented = (api.indexOf(fqn) === -1);
+      // Remove parents that are not part of the API
+      var parent;
+      var parents = e.doclet.augments;
+      if (parents) {
+        for (var i = parents.length - 1; i >= 0; --i) {
+          parent = parents[i];
+          if (api.indexOf(parent) === -1) {
+            parents.splice(i, 1);
+          }
+        }
+      }
+    }
+  }
+}
+
+exports.nodeVisitor = {
+
+  visitNode: function(node, e, parser, currentSourceName) {
+    // filter out non-API symbols before the addDocletRef finisher is called
+    e.finishers.unshift(filter);
+  }
+};

doc/plugins/inheritdoc.js

@@ -5,12 +5,12 @@
  * TODO: Remove this hack when https://github.com/jsdoc3/jsdoc/issues/53
  * is addressed.
  */
-exports.handlers = {
+exports.nodeVisitor = {
 
-  beforeParse: function(e) {
-    e.source = e.source.replace(
-        /\/\*\*\r?\n?\s*\* @(inheritDoc|override)\r?\n?\s*\*\/\r?\n?/g,
-        "/***\n *\n */\n");
+  visitNode: function(node, e, parser, currentSourceName) {
+    if (/@(inheritDoc|override)(\n|\r)/.test(e.comment)) {
+      e.preventDefault = true;
+    }
   }
 
 };

src/objectliterals.jsdoc

@@ -8,7 +8,8 @@
  * @property {ol.RendererHint|undefined} renderer Renderer.
  * @property {Array.<ol.RendererHint>|undefined} renderers Renderers.
  * @property {Element|string} target The container for the map.
- * @property {ol.IView|undefined} view View.
+ * @property {ol.IView|undefined} view The map's view. Currently
+ *     {@link ol.View2D} is available as view.
  */
 
 /**

src/ol/projection.jsdoc

@@ -0,0 +1,3 @@
+/**
+ * @namespace ol.projection
+ */

src/ol/projection/projection.js

@@ -671,7 +671,7 @@ ol.projection.transformWithProjections =
 
 /**
  * @param {ol.Proj4jsProjectionOptions} options Proj4js projection options.
- * @return {ol.Proj4jsProjection_} Proj4js projection.
+ * @return {ol.Projection} Proj4js projection.
  */
 ol.projection.configureProj4jsProjection = function(options) {
   goog.asserts.assert(!goog.object.containsKey(