From 2fd185c966474d4c2dfaba6568dce7576d383060 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Wed, 10 Apr 2013 01:44:40 +0200 Subject: [PATCH 01/10] Only document the exported API, not every symbol There is more work to be done, because this filters out more than desired, and we don't have events documented yet. --- build.py | 1 + doc/conf.json | 6 +++- doc/plugins/exports.js | 70 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 76 insertions(+), 1 deletion(-) create mode 100644 doc/plugins/exports.js diff --git a/build.py b/build.py index c2c5685a2b..b94352bd28 100755 --- a/build.py +++ b/build.py @@ -572,6 +572,7 @@ virtual('doc', 'build/jsdoc-%(BRANCH)s-timestamp' % vars(variables)) @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', diff --git a/doc/conf.json b/doc/conf.json index 986a90ec61..842c424266 100644 --- a/doc/conf.json +++ b/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" }, diff --git a/doc/plugins/exports.js b/doc/plugins/exports.js new file mode 100644 index 0000000000..d7c1848fae --- /dev/null +++ b/doc/plugins/exports.js @@ -0,0 +1,70 @@ +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)); + +var types = fs.readFileSync('build/src/external/src/types.js', encoding); +collectExports(types); +var typedefs = types.match(/goog\.provide\('[^']*'\)/g); +var typedef, namespace; +for (var i = 0, ii = typedefs.length; i < ii; ++ i) { + typedef = typedefs[i].match(/'([^']*)'/)[1]; + api.push(typedef); + namespace = typedef.substr(0, typedef.lastIndexOf('.')); + if (api.indexOf(namespace) === -1) { + api.push(namespace); + } +} + + +exports.handlers = { + + beforeParse: function(e) { + if (/\.js$/.test(e.filename)) { + collectExports(e.source); + } + }, + + newDoclet: function(e) { + var fqn = e.doclet.longname; + if (fqn) { + if (api.indexOf(fqn) === -1) { + e.doclet.undocumented = true; + } + } + } + +}; + + +exports.nodeVisitor = { + + visitNode: function(node, e, parser, currentSourceName) { + if (e.code) { + //console.log(e.source); + } + } +}; \ No newline at end of file From 551a5f06ff7573f777c2e91a5da742b413e2bb3c Mon Sep 17 00:00:00 2001 From: ahocevar Date: Wed, 10 Apr 2013 01:45:21 +0200 Subject: [PATCH 02/10] Nicer way to fix @inheritDoc --- doc/plugins/inheritdoc.js | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/plugins/inheritdoc.js b/doc/plugins/inheritdoc.js index 56f9a48d71..136bf385c8 100644 --- a/doc/plugins/inheritdoc.js +++ b/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; + } } }; \ No newline at end of file From 6f94ec6fe7121719d686ed013c81965d25f8ae86 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Wed, 10 Apr 2013 10:57:36 +0200 Subject: [PATCH 03/10] Adding params of API symbols to the API This makes the API docs complete. What still needs to be documented is API events, but this deserves a separate pull request. --- doc/plugins/exports.js | 49 +++++++++++++++++++++++----------------- src/objectliterals.jsdoc | 3 ++- 2 files changed, 30 insertions(+), 22 deletions(-) diff --git a/doc/plugins/exports.js b/doc/plugins/exports.js index d7c1848fae..8e483e3c59 100644 --- a/doc/plugins/exports.js +++ b/doc/plugins/exports.js @@ -23,21 +23,8 @@ function collectExports(source) { var encoding = env.conf.encoding || 'utf8'; var fs = require('jsdoc/fs'); - collectExports(fs.readFileSync('build/src/external/src/exports.js', encoding)); - -var types = fs.readFileSync('build/src/external/src/types.js', encoding); -collectExports(types); -var typedefs = types.match(/goog\.provide\('[^']*'\)/g); -var typedef, namespace; -for (var i = 0, ii = typedefs.length; i < ii; ++ i) { - typedef = typedefs[i].match(/'([^']*)'/)[1]; - api.push(typedef); - namespace = typedef.substr(0, typedef.lastIndexOf('.')); - if (api.indexOf(namespace) === -1) { - api.push(namespace); - } -} +collectExports(fs.readFileSync('build/src/external/src/types.js', encoding)); exports.handlers = { @@ -49,10 +36,22 @@ exports.handlers = { }, newDoclet: function(e) { - var fqn = e.doclet.longname; - if (fqn) { - if (api.indexOf(fqn) === -1) { - e.doclet.undocumented = true; + if (!e.doclet.undocumented) { + // 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); + } + } + } + } } } } @@ -60,11 +59,19 @@ exports.handlers = { }; +function filter(e) { + if (e.doclet) { + var fqn = e.doclet.longname; + if (fqn) { + e.doclet.undocumented = (api.indexOf(fqn) === -1); + } + } +} + exports.nodeVisitor = { visitNode: function(node, e, parser, currentSourceName) { - if (e.code) { - //console.log(e.source); - } + // filter out non-API symbols before the addDocletRef finisher is called + e.finishers.unshift(filter); } }; \ No newline at end of file diff --git a/src/objectliterals.jsdoc b/src/objectliterals.jsdoc index 61bdecede8..7bed4db3d2 100644 --- a/src/objectliterals.jsdoc +++ b/src/objectliterals.jsdoc @@ -8,7 +8,8 @@ * @property {ol.RendererHint|undefined} renderer Renderer. * @property {Array.|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. */ /** From 423ba5c0e4970482e2ac1eef3b885f9223093639 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Wed, 10 Apr 2013 11:04:39 +0200 Subject: [PATCH 04/10] A few lines explaining what the exports.js plugin does --- doc/plugins/exports.js | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/plugins/exports.js b/doc/plugins/exports.js index 8e483e3c59..90b202de2a 100644 --- a/doc/plugins/exports.js +++ b/doc/plugins/exports.js @@ -1,3 +1,9 @@ +/* + * 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) { From 9cb85ea9a9df13e3eddd2cd43f4bc6a1b3f2c129 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Wed, 10 Apr 2013 11:18:23 +0200 Subject: [PATCH 05/10] Adding the projection namespace --- src/ol/projection.jsdoc | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 src/ol/projection.jsdoc diff --git a/src/ol/projection.jsdoc b/src/ol/projection.jsdoc new file mode 100644 index 0000000000..14ead54128 --- /dev/null +++ b/src/ol/projection.jsdoc @@ -0,0 +1,3 @@ +/** + * @namespace ol.projection + */ \ No newline at end of file From 8acfa087661b3d34b1b241dd1ed5d895c6fd4466 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Wed, 10 Apr 2013 11:24:27 +0200 Subject: [PATCH 06/10] Making the linter happy Although *.jsdoc files are none of the linter's business... --- src/ol/projection.jsdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/ol/projection.jsdoc b/src/ol/projection.jsdoc index 14ead54128..f325db2bba 100644 --- a/src/ol/projection.jsdoc +++ b/src/ol/projection.jsdoc @@ -1,3 +1,3 @@ /** * @namespace ol.projection - */ \ No newline at end of file + */ From 1e0e30a9eda0f6815861b3d240007ba307b66c8d Mon Sep 17 00:00:00 2001 From: ahocevar Date: Wed, 10 Apr 2013 11:34:03 +0200 Subject: [PATCH 07/10] Use a public return type for a public function --- src/ol/projection/projection.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/ol/projection/projection.js b/src/ol/projection/projection.js index 22d3cd9dfd..19816b69c2 100644 --- a/src/ol/projection/projection.js +++ b/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( From 7a50295c49e4f044c9e7d5ec7ed989005bae31e9 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Wed, 10 Apr 2013 13:18:22 +0200 Subject: [PATCH 08/10] Making @elemoine and GitHub happy Reminder to self: everyone wants a new line at the end of a file. --- doc/plugins/exports.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/plugins/exports.js b/doc/plugins/exports.js index 90b202de2a..cc8e949b2a 100644 --- a/doc/plugins/exports.js +++ b/doc/plugins/exports.js @@ -80,4 +80,4 @@ exports.nodeVisitor = { // filter out non-API symbols before the addDocletRef finisher is called e.finishers.unshift(filter); } -}; \ No newline at end of file +}; From 71c32d3554adcf3d1700a30abffdf5238ef52f6a Mon Sep 17 00:00:00 2001 From: ahocevar Date: Wed, 10 Apr 2013 13:59:32 +0200 Subject: [PATCH 09/10] Don't use the undocumented property before it is set This actually avoids addition of params of symbols that are not part of the API. --- doc/plugins/exports.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/plugins/exports.js b/doc/plugins/exports.js index cc8e949b2a..2ab9b00b0d 100644 --- a/doc/plugins/exports.js +++ b/doc/plugins/exports.js @@ -42,7 +42,7 @@ exports.handlers = { }, newDoclet: function(e) { - if (!e.doclet.undocumented) { + if (api.indexOf(e.doclet.longname) > -1) { // Add params of API symbols to the API var names, name; var params = e.doclet.params; From 12cd3672bc74105fe266951d195546885e851632 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Wed, 10 Apr 2013 15:06:12 +0200 Subject: [PATCH 10/10] Remove "Inherited from" for non-API parents --- doc/plugins/exports.js | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/doc/plugins/exports.js b/doc/plugins/exports.js index 2ab9b00b0d..f2b19c2d57 100644 --- a/doc/plugins/exports.js +++ b/doc/plugins/exports.js @@ -70,6 +70,17 @@ function filter(e) { 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); + } + } + } } } }