Merge pull request #1904 from ahocevar/doc-improvements

API doc improvements

apidoc/plugins/exports.js

@@ -73,7 +73,7 @@ exports.handlers = {
       }
     }
     if (api.indexOf(e.doclet.longname) > -1) {
-      // Add params and events of API symbols to the API
+      // Add params, links and events of API symbols to the API
       var names, name;
       var params = e.doclet.params;
       if (params) {
@@ -82,55 +82,61 @@ exports.handlers = {
           if (names) {
             for (j = 0, jj=names.length; j < jj; ++j) {
               name = names[j];
-              if (api.indexOf(name) === -1) {
+              if (unexported.indexOf(name) === -1) {
                 unexported.push(name);
               }
             }
           }
         }
       }
+      var links = e.doclet.comment.match(/\{@link ([^\}]*)\}/g);
+      if (links) {
+        for (i=0, ii=links.length; i < ii; ++i) {
+          if (unexported.indexOf(links[i]) === -1) {
+            unexported.push(links[i].match(/\{@link (.*)\}/)[1]);
+          }
+        }
+      }
       var fires = e.doclet.fires;
       var event;
       if (fires) {
         for (i = 0, ii = fires.length; i < ii; ++i) {
           event = fires[i].split(' ').pop();
           name = event.replace('event:', '');
-          if (api.indexOf(name) === -1) {
+          if (unexported.indexOf(name) === -1) {
             unexported.push(name);
           }
         }
       }
     }
-  }
+  },
   
-};
+  parseComplete: function(e) {
-
+    for (var j = e.doclets.length - 1; j >= 0; --j) {
-
+      var doclet = e.doclets[j];
-function filter(e) {
+      if (doclet.kind == 'namespace') {
-  if (e.doclet) {
+        continue;
-    var fqn = e.doclet.longname;
+      }
-    if (fqn) {
+      var fqn = doclet.longname;
-      e.doclet.undocumented = (api.indexOf(fqn) === -1 && unexported.indexOf(fqn) === -1);
+      if (fqn) {
-      e.doclet.unexported = (unexported.indexOf(fqn) !== -1);
+        doclet.unexported = (unexported.indexOf(fqn) !== -1);
-      // Remove parents that are not part of the API
+        var undocumented = (api.indexOf(fqn) === -1 && !doclet.unexported);
-      var parent;
+        // Remove parents that are not part of the API
-      var parents = e.doclet.augments;
+        var parent;
-      if (parents) {
+        var parents = doclet.augments;
-        for (var i = parents.length - 1; i >= 0; --i) {
+        if (parents) {
-          parent = parents[i];
+          for (var i = parents.length - 1; i >= 0; --i) {
-          if (api.indexOf(parent) === -1) {
+            parent = parents[i];
-            parents.splice(i, 1);
+            if (api.indexOf(parent) === -1 && unexported.indexOf(parent) === -1) {
+              parents.splice(i, 1);
+            }
           }
         }
+        if (undocumented) {
+          e.doclets.splice(j, 1);
+        }
       }
     }
   }
-}
 
-exports.nodeVisitor = {
-
-  visitNode: function(node, e, parser, currentSourceName) {
-    // filter out non-API symbols before the addDocletRef finisher is called
-    e.finishers.unshift(filter);
-  }
 };

src/ol/iview.js

@@ -6,7 +6,7 @@ goog.require('ol.IView3D');
 
 
 /**
- * Interface for views.
+ * Interface for views. Currently {@link ol.View2D} is implemented.
  * @interface
  */
 ol.IView = function() {

src/ol/render.jsdoc

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

src/ol/render/ivectorcontext.js

@@ -5,6 +5,8 @@ goog.provide('ol.render.IVectorContext');
 
 
 /**
+ * VectorContext interface. Currently implemented by
+ * {@link ol.render.canvas.Immediate}
  * @interface
  * @todo stability experimental
  */