diff --git a/build.py b/build.py index 28f1fbb615..a2f90bdcbc 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..f2b19c2d57 --- /dev/null +++ b/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); + } +}; 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 diff --git a/src/objectliterals.jsdoc b/src/objectliterals.jsdoc index 1a44054f80..2a10058c7a 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. */ /** diff --git a/src/ol/projection.jsdoc b/src/ol/projection.jsdoc new file mode 100644 index 0000000000..f325db2bba --- /dev/null +++ b/src/ol/projection.jsdoc @@ -0,0 +1,3 @@ +/** + * @namespace ol.projection + */ 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(