From a09f7fb3bb0323ada6a8eae2401bc66a91d8bb0f Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 19 Apr 2018 17:27:02 -0600 Subject: [PATCH] Clean lint from jsdoc config --- .eslintignore | 1 + config/jsdoc/api/plugins/api.js | 26 +- config/jsdoc/api/plugins/events.js | 14 +- config/jsdoc/api/plugins/inheritdoc.js | 18 +- config/jsdoc/api/plugins/observable.js | 16 +- config/jsdoc/api/plugins/typedefs.js | 57 +- config/jsdoc/api/template/publish.js | 748 +++++++++++++------------ config/jsdoc/info/define-plugin.js | 6 +- config/jsdoc/info/virtual-plugin.js | 2 +- package.json | 2 +- 10 files changed, 448 insertions(+), 442 deletions(-) diff --git a/.eslintignore b/.eslintignore index d6f9d6349f..dcc754f246 100644 --- a/.eslintignore +++ b/.eslintignore @@ -1,3 +1,4 @@ examples/Jugl.js examples/resources/ build/package/**/*webgl* +config/jsdoc/api/template/static/scripts/ \ No newline at end of file diff --git a/config/jsdoc/api/plugins/api.js b/config/jsdoc/api/plugins/api.js index c0e795eff2..8204835459 100644 --- a/config/jsdoc/api/plugins/api.js +++ b/config/jsdoc/api/plugins/api.js @@ -1,5 +1,6 @@ /** * Define an @api tag + * @param {Object} dictionary The tag dictionary. */ exports.defineTags = function(dictionary) { dictionary.defineTag('api', { @@ -8,32 +9,31 @@ exports.defineTags = function(dictionary) { canHaveName: false, onTagged: function(doclet, tag) { includeTypes(doclet); - doclet.stability = "stable"; + doclet.stability = 'stable'; } }); }; - /* * Based on @api annotations, and assuming that items with no @api annotation * should not be documented, this plugin removes undocumented symbols * from the documentation. */ -var api = []; -var classes = {}; -var types = {}; +const api = []; +const classes = {}; +const types = {}; function hasApiMembers(doclet) { return doclet.longname.split('#')[0] == this.longname; } function includeAugments(doclet) { - var augments = doclet.augments; + const augments = doclet.augments; if (augments) { - var cls; - for (var i = augments.length - 1; i >= 0; --i) { + let cls; + for (let i = augments.length - 1; i >= 0; --i) { cls = classes[augments[i]]; if (cls) { includeAugments(cls); @@ -68,7 +68,7 @@ function includeAugments(doclet) { function extractTypes(item) { item.type.names.forEach(function(type) { - var match = type.match(/^(.*<)?([^>]*)>?$/); + const match = type.match(/^(.*<)?([^>]*)>?$/); if (match) { types[match[2]] = true; } @@ -94,7 +94,7 @@ function includeTypes(doclet) { exports.handlers = { newDoclet: function(e) { - var doclet = e.doclet; + const doclet = e.doclet; // Keep track of api items - needed in parseComplete to determine classes // with api members. if (doclet.meta.filename == 'olx.js' && doclet.kind == 'typedef') { @@ -114,9 +114,9 @@ exports.handlers = { }, parseComplete: function(e) { - var doclets = e.doclets; - for (var i = doclets.length - 1; i >= 0; --i) { - var doclet = doclets[i]; + const doclets = e.doclets; + for (let i = doclets.length - 1; i >= 0; --i) { + const doclet = doclets[i]; if (doclet.stability || doclet.namespace_) { if (doclet.kind == 'class') { includeAugments(doclet); diff --git a/config/jsdoc/api/plugins/events.js b/config/jsdoc/api/plugins/events.js index 52141b2427..b1ffa9dfba 100644 --- a/config/jsdoc/api/plugins/events.js +++ b/config/jsdoc/api/plugins/events.js @@ -1,11 +1,11 @@ -var events = {}; -var classes = {}; +const events = {}; +const classes = {}; exports.handlers = { newDoclet: function(e) { - var doclet = e.doclet; - var cls; + const doclet = e.doclet; + let cls; if (doclet.kind == 'event') { cls = doclet.longname.split('#')[0]; if (!(cls in events)) { @@ -18,8 +18,8 @@ exports.handlers = { }, parseComplete: function(e) { - var doclets = e.doclets; - var doclet, i, ii, j, jj, event, fires; + const doclets = e.doclets; + let doclet, i, ii, j, jj, event, fires; for (i = 0, ii = doclets.length - 1; i < ii; ++i) { doclet = doclets[i]; if (doclet.fires) { @@ -28,7 +28,7 @@ exports.handlers = { 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]); + fires.push.apply(fires, events[event]); } else { fires.push(doclet.fires[j]); } diff --git a/config/jsdoc/api/plugins/inheritdoc.js b/config/jsdoc/api/plugins/inheritdoc.js index 04397af7c6..e252269bcc 100644 --- a/config/jsdoc/api/plugins/inheritdoc.js +++ b/config/jsdoc/api/plugins/inheritdoc.js @@ -19,16 +19,16 @@ exports.defineTags = function(dictionary) { }; -var lookup = {}; -var incompleteByClass = {}; -var keepKeys = ['comment', 'meta', 'name', 'memberof', 'longname', 'augment', - 'stability']; +const lookup = {}; +const incompleteByClass = {}; +const keepKeys = ['comment', 'meta', 'name', 'memberof', 'longname', 'augment', + 'stability']; exports.handlers = { newDoclet: function(e) { - var doclet = e.doclet; - var incompletes; + const doclet = e.doclet; + let incompletes; if (!(doclet.longname in lookup)) { lookup[doclet.longname] = []; } @@ -45,9 +45,9 @@ exports.handlers = { }, parseComplete: function(e) { - var ancestors, candidate, candidates, doclet, i, j, k, l, key; - var incompleteDoclet, stability, incomplete, incompletes; - var doclets = e.doclets; + let ancestors, candidate, candidates, doclet, i, j, k, l, key; + let incompleteDoclet, stability, incomplete, incompletes; + const doclets = e.doclets; for (i = doclets.length - 1; i >= 0; --i) { doclet = doclets[i]; if (doclet.augments) { diff --git a/config/jsdoc/api/plugins/observable.js b/config/jsdoc/api/plugins/observable.js index 99b87e50a0..4622987d07 100644 --- a/config/jsdoc/api/plugins/observable.js +++ b/config/jsdoc/api/plugins/observable.js @@ -1,25 +1,25 @@ -var classes = {}; -var observables = {}; +const classes = {}; +const observables = {}; exports.handlers = { newDoclet: function(e) { - var doclet = e.doclet; + const 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; + const doclets = e.doclets; + let 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/, ''); + let name = doclet.name.replace(/^[sg]et/, ''); name = name.substr(0, 1).toLowerCase() + name.substr(1); - var key = doclet.longname.split('#')[0] + '#' + name; + const key = doclet.longname.split('#')[0] + '#' + name; doclet.observable = key; if (!observables[key]) { observables[key] = {}; @@ -27,7 +27,7 @@ exports.handlers = { observable = observables[key]; observable.name = name; observable.readonly = typeof observable.readonly == 'boolean' ? - observable.readonly : true; + observable.readonly : true; if (doclet.name.indexOf('get') === 0) { observable.type = doclet.returns[0].type; observable.description = doclet.returns[0].description; diff --git a/config/jsdoc/api/plugins/typedefs.js b/config/jsdoc/api/plugins/typedefs.js index 67fe8ad4df..d2ff907286 100644 --- a/config/jsdoc/api/plugins/typedefs.js +++ b/config/jsdoc/api/plugins/typedefs.js @@ -3,19 +3,19 @@ * Changes @enum annotations into @typedef. */ -var lastOlxTypedef = null; -var olxTypes = {}; +let lastOlxTypedef = null; +const olxTypes = {}; // names of the olx typenames -var olxTypeNames = []; +const olxTypeNames = []; // types that are undefined or typedefs containing undefined -var undefinedLikes = null; +let undefinedLikes = null; 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]; + for (let j = 0, jj = params.length; j < jj; ++j) { + const param = params[j]; + const types = param.type.names; + for (let k = 0, kk = types.length; k < kk; ++k) { + const name = types[k]; if (name in olxTypes) { param.subparams = olxTypes[name]; // TODO addSubparams(param.subparams); @@ -30,20 +30,22 @@ function addSubparams(params) { /** * Changes the description of the param, if it is found to be a required * option of an olxTypeName. + * @param {Object} doclet The doclet. + * @returns {Object} The modified doclet. */ -function markRequiredIfNeeded(doclet){ - var memberof = doclet.memberof; +function markRequiredIfNeeded(doclet) { + const memberof = doclet.memberof; // only check doclets that belong to an olxTypeName if (!memberof || olxTypeNames.indexOf(memberof) == -1) { return doclet; } - var types = doclet.type.names; - var isRequiredParam = true; + const types = doclet.type.names; + let isRequiredParam = true; // iterate over all types that are like-undefined (see above for explanation) - for (var idx = undefinedLikes.length - 1; idx >= 0; idx--) { - var undefinedLike = undefinedLikes[idx]; + for (let idx = undefinedLikes.length - 1; idx >= 0; idx--) { + const undefinedLike = undefinedLikes[idx]; // … if the current types contains a type that is undefined-like, // it is not required. if (types.indexOf(undefinedLike) != -1) { @@ -52,9 +54,9 @@ function markRequiredIfNeeded(doclet){ } if (isRequiredParam) { - var reqSnippet = 'Required.

'; - var endsWithP = /<\/p>$/i; - var description = doclet.description; + const reqSnippet = 'Required.

'; + const endsWithP = /<\/p>$/i; + let description = doclet.description; if (description && endsWithP.test(description)) { description = description.replace(endsWithP, ' ' + reqSnippet); } else if (doclet.description === undefined) { @@ -69,13 +71,14 @@ function markRequiredIfNeeded(doclet){ * Iterates over all doclets and finds the names of types that contain * undefined. Stores the names in the global variable undefinedLikes, so * that e.g. markRequiredIfNeeded can use these. + * @param {Array} doclets The doclets. */ function findTypesLikeUndefined(doclets) { undefinedLikes = ['undefined']; // include type 'undefined' explicitly - for (var i = doclets.length - 1; i >= 0; --i) { - var doclet = doclets[i]; - if(doclet.kind === 'typedef') { - var types = doclet.type.names; + for (let i = doclets.length - 1; i >= 0; --i) { + const doclet = doclets[i]; + if (doclet.kind === 'typedef') { + const types = doclet.type.names; if (types.indexOf('undefined') !== -1) { // the typedef contains 'undefined', so it self is undefinedLike. undefinedLikes.push(doclet.longname); @@ -87,7 +90,7 @@ function findTypesLikeUndefined(doclets) { exports.handlers = { newDoclet: function(e) { - var doclet = e.doclet; + const doclet = e.doclet; if (doclet.meta.filename == 'olx.js') { if (doclet.kind == 'typedef') { lastOlxTypedef = doclet; @@ -108,11 +111,11 @@ exports.handlers = { }, parseComplete: function(e) { - var doclets = e.doclets; + const doclets = e.doclets; findTypesLikeUndefined(doclets); - for (var i = doclets.length - 1; i >= 0; --i) { - var doclet = doclets[i]; - var params = doclet.params; + for (let i = doclets.length - 1; i >= 0; --i) { + const doclet = doclets[i]; + const params = doclet.params; if (params) { addSubparams(params); } diff --git a/config/jsdoc/api/template/publish.js b/config/jsdoc/api/template/publish.js index c98be1de77..aa17a11b8a 100644 --- a/config/jsdoc/api/template/publish.js +++ b/config/jsdoc/api/template/publish.js @@ -1,152 +1,152 @@ /*global env: true */ -var template = require('jsdoc/lib/jsdoc/template'), - fs = require('jsdoc/lib/jsdoc/fs'), - path = require('jsdoc/lib/jsdoc/path'), - taffy = require('taffydb').taffy, - handle = require('jsdoc/lib/jsdoc/util/error').handle, - helper = require('jsdoc/lib/jsdoc/util/templateHelper'), - _ = require('underscore'), - htmlsafe = helper.htmlsafe, - linkto = helper.linkto, - resolveAuthorLinks = helper.resolveAuthorLinks, - scopeToPunc = helper.scopeToPunc, - hasOwnProp = Object.prototype.hasOwnProperty, - data, - view, - outdir = env.opts.destination; +const template = require('jsdoc/lib/jsdoc/template'); +const fs = require('jsdoc/lib/jsdoc/fs'); +const path = require('jsdoc/lib/jsdoc/path'); +const taffy = require('taffydb').taffy; +const handle = require('jsdoc/lib/jsdoc/util/error').handle; +const helper = require('jsdoc/lib/jsdoc/util/templateHelper'); +const _ = require('underscore'); +const htmlsafe = helper.htmlsafe; +const linkto = helper.linkto; +const resolveAuthorLinks = helper.resolveAuthorLinks; +const hasOwnProp = Object.prototype.hasOwnProperty; +const outdir = env.opts.destination; + +let view; +let data; function find(spec) { - return helper.find(data, spec); + return helper.find(data, spec); } function tutoriallink(tutorial) { - return helper.toTutorial(tutorial, null, { tag: 'em', classname: 'disabled', prefix: 'Tutorial: ' }); + return helper.toTutorial(tutorial, null, {tag: 'em', classname: 'disabled', prefix: 'Tutorial: '}); } function getAncestorLinks(doclet) { - return helper.getAncestorLinks(data, doclet); + return helper.getAncestorLinks(data, doclet); } function hashToLink(doclet, hash) { - if ( !/^(#.+)/.test(hash) ) { return hash; } + if (!/^(#.+)/.test(hash)) { + return hash; + } - var url = helper.createLink(doclet); + let url = helper.createLink(doclet); - url = url.replace(/(#.+|$)/, hash); - return '' + hash + ''; + url = url.replace(/(#.+|$)/, hash); + return '' + hash + ''; } function needsSignature(doclet) { - var needsSig = false; + let needsSig = false; - // function and class definitions always get a signature - if (doclet.kind === 'function' || doclet.kind === 'class') { - needsSig = true; - } + // function and class definitions always get a signature + if (doclet.kind === 'function' || doclet.kind === 'class') { + needsSig = true; + } else if (doclet.kind === 'typedef' && doclet.type && doclet.type.names && + doclet.type.names.length) { // typedefs that contain functions get a signature, too - else if (doclet.kind === 'typedef' && doclet.type && doclet.type.names && - doclet.type.names.length) { - for (var i = 0, l = doclet.type.names.length; i < l; i++) { - if (doclet.type.names[i].toLowerCase() === 'function') { - needsSig = true; - break; - } - } + for (let i = 0, l = doclet.type.names.length; i < l; i++) { + if (doclet.type.names[i].toLowerCase() === 'function') { + needsSig = true; + break; + } } + } - return needsSig; + return needsSig; } function addSignatureParams(f) { - var params = helper.getSignatureParams(f, 'optional'); + const params = helper.getSignatureParams(f, 'optional'); - f.signature = (f.signature || '') + '('+params.join(', ')+')'; + f.signature = (f.signature || '') + '(' + params.join(', ') + ')'; } function addSignatureReturns(f) { - var returnTypes = helper.getSignatureReturns(f); + const returnTypes = helper.getSignatureReturns(f); - f.signature = ''+(f.signature || '') + ''; + f.signature = '' + (f.signature || '') + ''; - if (returnTypes.length) { - f.signature += ''+(returnTypes.length ? '{'+returnTypes.join('|')+'}' : '')+''; - } + if (returnTypes.length) { + f.signature += '' + (returnTypes.length ? '{' + returnTypes.join('|') + '}' : '') + ''; + } } function addSignatureTypes(f) { - var types = helper.getSignatureTypes(f); + const types = helper.getSignatureTypes(f); - f.signature = (f.signature || '') + ''+(types.length? ' :'+types.join('|') : '')+' '; + f.signature = (f.signature || '') + '' + (types.length ? ' :' + types.join('|') : '') + ' '; } function shortenPaths(files, commonPrefix) { - // always use forward slashes - var regexp = new RegExp('\\\\', 'g'); + // always use forward slashes + const regexp = new RegExp('\\\\', 'g'); - Object.keys(files).forEach(function(file) { - files[file].shortened = files[file].resolved.replace(commonPrefix, '') - .replace(regexp, '/'); - }); + Object.keys(files).forEach(function(file) { + files[file].shortened = files[file].resolved.replace(commonPrefix, '') + .replace(regexp, '/'); + }); - return files; + return files; } function resolveSourcePath(filepath) { - return path.resolve(process.cwd(), filepath); + return path.resolve(process.cwd(), filepath); } function getPathFromDoclet(doclet) { - if (!doclet.meta) { - return; - } + if (!doclet.meta) { + return; + } - var filepath = doclet.meta.path && doclet.meta.path !== 'null' ? - doclet.meta.path + '/' + doclet.meta.filename.split(/[\/\\]/).pop() : - doclet.meta.filename; + const filepath = doclet.meta.path && doclet.meta.path !== 'null' ? + doclet.meta.path + '/' + doclet.meta.filename.split(/[\/\\]/).pop() : + doclet.meta.filename; - return filepath; + return filepath; } function generate(title, docs, filename, resolveLinks) { - resolveLinks = resolveLinks === false ? false : true; + resolveLinks = resolveLinks === false ? false : true; - var docData = { - filename: filename, - title: title, - docs: docs, - packageInfo: ( find({kind: 'package'}) || [] ) [0] - }; + const docData = { + filename: filename, + title: title, + docs: docs, + packageInfo: (find({kind: 'package'}) || []) [0] + }; - var outpath = path.join(outdir, filename), - html = view.render('container.tmpl', docData); + const outpath = path.join(outdir, filename); + let html = view.render('container.tmpl', docData); - if (resolveLinks) { - html = helper.resolveLinks(html); // turn {@link foo} into foo - } + if (resolveLinks) { + html = helper.resolveLinks(html); // turn {@link foo} into foo + } - fs.writeFileSync(outpath, html, 'utf8'); + fs.writeFileSync(outpath, html, 'utf8'); } function generateSourceFiles(sourceFiles) { - Object.keys(sourceFiles).forEach(function(file) { - var source; - // links are keyed to the shortened path in each doclet's `meta.filename` property - var sourceOutfile = helper.getUniqueFilename(sourceFiles[file].shortened); - helper.registerLink(sourceFiles[file].shortened, sourceOutfile); + Object.keys(sourceFiles).forEach(function(file) { + let source; + // links are keyed to the shortened path in each doclet's `meta.filename` property + const sourceOutfile = helper.getUniqueFilename(sourceFiles[file].shortened); + helper.registerLink(sourceFiles[file].shortened, sourceOutfile); - try { - source = { - kind: 'source', - code: helper.htmlsafe( fs.readFileSync(sourceFiles[file].resolved, 'utf8') ) - }; - } - catch(e) { - handle(e); - } + try { + source = { + kind: 'source', + code: helper.htmlsafe(fs.readFileSync(sourceFiles[file].resolved, 'utf8')) + }; + } catch (e) { + handle(e); + } - generate('Source: ' + sourceFiles[file].shortened, [source], sourceOutfile, - false); - }); + generate('Source: ' + sourceFiles[file].shortened, [source], sourceOutfile, + false); + }); } /** @@ -161,346 +161,348 @@ function generateSourceFiles(sourceFiles) { * @param {Array.} modules - The array of module doclets to search. */ function attachModuleSymbols(doclets, modules) { - var symbols = {}; + const symbols = {}; - // build a lookup table - doclets.forEach(function(symbol) { - symbols[symbol.longname] = symbol; - }); + // build a lookup table + doclets.forEach(function(symbol) { + symbols[symbol.longname] = symbol; + }); - return modules.map(function(module) { - if (symbols[module.longname]) { - module.module = symbols[module.longname]; - module.module.name = module.module.name.replace('module:', 'require("') + '")'; - } - }); + modules.forEach(function(module) { + if (symbols[module.longname]) { + module.module = symbols[module.longname]; + module.module.name = module.module.name.replace('module:', 'require("') + '")'; + } + }); } /** * Create the navigation sidebar. * @param {object} members The members that will be used to create the sidebar. - * @param {array} members.classes - * @param {array} members.externals - * @param {array} members.globals - * @param {array} members.mixins - * @param {array} members.modules - * @param {array} members.namespaces - * @param {array} members.tutorials - * @param {array} members.events + * @param {Array} members.classes Classes. + * @param {Array} members.externals Externals. + * @param {Array} members.globals Globals. + * @param {Array} members.mixins Mixins. + * @param {Array} members.modules Modules. + * @param {Array} members.namespaces Namespaces. + * @param {Array} members.tutorials Tutorials. + * @param {Array} members.events Events. * @return {string} The HTML for the navigation sidebar. */ function buildNav(members) { - var nav = []; - // merge namespaces and classes, then sort - var merged = members.namespaces.concat(members.classes); - merged.sort(function (a, b) { - if (a.longname > b.longname) - return 1; - if (a.longname < b.longname) - return -1; - return 0; - }); - _.each(merged, function (v) { - // exclude 'olx' and interfaces from sidebar - if (v.longname.indexOf('olx') !== 0 && v.interface !== true) { - if (v.kind == 'namespace') { - nav.push({ - type: 'namespace', - longname: v.longname, - name: v.name, - members: find({ - kind: 'member', - memberof: v.longname - }), - methods: find({ - kind: 'function', - memberof: v.longname - }), - typedefs: find({ - kind: 'typedef', - memberof: v.longname - }), - events: find({ - kind: 'event', - memberof: v.longname - }) - }); - } - if (v.kind == 'class') { - nav.push({ - type: 'class', - longname: v.longname, - name: v.name, - members: find({ - kind: 'member', - memberof: v.longname - }), - methods: find({ - kind: 'function', - memberof: v.longname - }), - typedefs: find({ - kind: 'typedef', - memberof: v.longname - }), - fires: v.fires, - events: find({ - kind: 'event', - memberof: v.longname - }) - }); - } + const nav = []; + // merge namespaces and classes, then sort + const merged = members.namespaces.concat(members.classes); + merged.sort(function(a, b) { + if (a.longname > b.longname) { + return 1; + } + if (a.longname < b.longname) { + return -1; + } + return 0; + }); + _.each(merged, function(v) { + // exclude 'olx' and interfaces from sidebar + if (v.longname.indexOf('olx') !== 0 && v.interface !== true) { + if (v.kind == 'namespace') { + nav.push({ + type: 'namespace', + longname: v.longname, + name: v.name, + members: find({ + kind: 'member', + memberof: v.longname + }), + methods: find({ + kind: 'function', + memberof: v.longname + }), + typedefs: find({ + kind: 'typedef', + memberof: v.longname + }), + events: find({ + kind: 'event', + memberof: v.longname + }) + }); } - }); - return nav; + if (v.kind == 'class') { + nav.push({ + type: 'class', + longname: v.longname, + name: v.name, + members: find({ + kind: 'member', + memberof: v.longname + }), + methods: find({ + kind: 'function', + memberof: v.longname + }), + typedefs: find({ + kind: 'typedef', + memberof: v.longname + }), + fires: v.fires, + events: find({ + kind: 'event', + memberof: v.longname + }) + }); + } + } + }); + return nav; } /** - @param {TAFFY} taffyData See . - @param {object} opts - @param {Tutorial} tutorials + * @param {Object} taffyData See . + * @param {Object} opts Options. + * @param {Object} tutorials Tutorials. */ exports.publish = function(taffyData, opts, tutorials) { - data = taffyData; + data = taffyData; - var conf = env.conf.templates || {}; - conf['default'] = conf['default'] || {}; + const conf = env.conf.templates || {}; + conf['default'] = conf['default'] || {}; - var templatePath = opts.template; - view = new template.Template(templatePath + '/tmpl'); + const templatePath = opts.template; + view = new template.Template(templatePath + '/tmpl'); - // claim some special filenames in advance, so the All-Powerful Overseer of Filename Uniqueness - // doesn't try to hand them out later - var indexUrl = helper.getUniqueFilename('index'); - // don't call registerLink() on this one! 'index' is also a valid longname + // claim some special filenames in advance, so the All-Powerful Overseer of Filename Uniqueness + // doesn't try to hand them out later + const indexUrl = helper.getUniqueFilename('index'); + // don't call registerLink() on this one! 'index' is also a valid longname - var globalUrl = helper.getUniqueFilename('global'); - helper.registerLink('global', globalUrl); + const globalUrl = helper.getUniqueFilename('global'); + helper.registerLink('global', globalUrl); - // set up templating - view.layout = 'layout.tmpl'; + // set up templating + view.layout = 'layout.tmpl'; - // set up tutorials for helper - helper.setTutorials(tutorials); + // set up tutorials for helper + helper.setTutorials(tutorials); - data = helper.prune(data); - data.sort('longname, version, since'); - helper.addEventListeners(data); + data = helper.prune(data); + data.sort('longname, version, since'); + helper.addEventListeners(data); - var sourceFiles = {}; - var sourceFilePaths = []; - data().each(function(doclet) { - doclet.attribs = ''; + let sourceFiles = {}; + const sourceFilePaths = []; + data().each(function(doclet) { + doclet.attribs = ''; - if (doclet.examples) { - doclet.examples = doclet.examples.map(function(example) { - var caption, code; + if (doclet.examples) { + doclet.examples = doclet.examples.map(function(example) { + let caption, code; - if (example.match(/^\s*([\s\S]+?)<\/caption>(\s*[\n\r])([\s\S]+)$/i)) { - caption = RegExp.$1; - code = RegExp.$3; - } - - return { - caption: caption || '', - code: code || example - }; - }); - } - if (doclet.see) { - doclet.see.forEach(function(seeItem, i) { - doclet.see[i] = hashToLink(doclet, seeItem); - }); + if (example.match(/^\s*([\s\S]+?)<\/caption>(\s*[\n\r])([\s\S]+)$/i)) { + caption = RegExp.$1; + code = RegExp.$3; } - // build a list of source files - var sourcePath; - var resolvedSourcePath; - if (doclet.meta) { - sourcePath = getPathFromDoclet(doclet); - resolvedSourcePath = resolveSourcePath(sourcePath); - sourceFiles[sourcePath] = { - resolved: resolvedSourcePath, - shortened: null - }; - sourceFilePaths.push(resolvedSourcePath); - } - }); + return { + caption: caption || '', + code: code || example + }; + }); + } + if (doclet.see) { + doclet.see.forEach(function(seeItem, i) { + doclet.see[i] = hashToLink(doclet, seeItem); + }); + } - fs.mkPath(outdir); + // build a list of source files + let sourcePath; + let resolvedSourcePath; + if (doclet.meta) { + sourcePath = getPathFromDoclet(doclet); + resolvedSourcePath = resolveSourcePath(sourcePath); + sourceFiles[sourcePath] = { + resolved: resolvedSourcePath, + shortened: null + }; + sourceFilePaths.push(resolvedSourcePath); + } + }); - // copy the template's static files to outdir - var fromDir = path.join(templatePath, 'static'); - var staticFiles = fs.ls(fromDir, 3); + fs.mkPath(outdir); - staticFiles.forEach(function(fileName) { - var toDir = fs.toDir( fileName.replace(fromDir, outdir) ); + // copy the template's static files to outdir + const fromDir = path.join(templatePath, 'static'); + const staticFiles = fs.ls(fromDir, 3); + + staticFiles.forEach(function(fileName) { + const toDir = fs.toDir(fileName.replace(fromDir, outdir)); + fs.mkPath(toDir); + fs.copyFileSync(fileName, toDir); + }); + + // copy user-specified static files to outdir + let staticFilePaths; + let staticFileFilter; + let staticFileScanner; + if (conf['default'].staticFiles) { + staticFilePaths = conf['default'].staticFiles.paths || []; + staticFileFilter = new (require('jsdoc/lib/jsdoc/src/filter')).Filter(conf['default'].staticFiles); + staticFileScanner = new (require('jsdoc/lib/jsdoc/src/scanner')).Scanner(); + + staticFilePaths.forEach(function(filePath) { + const extraStaticFiles = staticFileScanner.scan([filePath], 10, staticFileFilter); + + extraStaticFiles.forEach(function(fileName) { + const sourcePath = fs.statSync(filePath).isDirectory() ? filePath : + path.dirname(filePath); + const toDir = fs.toDir(fileName.replace(sourcePath, outdir)); fs.mkPath(toDir); fs.copyFileSync(fileName, toDir); + }); }); + } - // copy user-specified static files to outdir - var staticFilePaths; - var staticFileFilter; - var staticFileScanner; - if (conf['default'].staticFiles) { - staticFilePaths = conf['default'].staticFiles.paths || []; - staticFileFilter = new (require('jsdoc/lib/jsdoc/src/filter')).Filter(conf['default'].staticFiles); - staticFileScanner = new (require('jsdoc/lib/jsdoc/src/scanner')).Scanner(); + if (sourceFilePaths.length) { + sourceFiles = shortenPaths(sourceFiles, path.commonPrefix(sourceFilePaths)); + } + data().each(function(doclet) { + const url = helper.createLink(doclet); + helper.registerLink(doclet.longname, url); - staticFilePaths.forEach(function(filePath) { - var extraStaticFiles = staticFileScanner.scan([filePath], 10, staticFileFilter); + // replace the filename with a shortened version of the full path + let docletPath; + if (doclet.meta) { + docletPath = getPathFromDoclet(doclet); + docletPath = sourceFiles[docletPath].shortened; + if (docletPath) { + doclet.meta.filename = docletPath; + } + } + }); - extraStaticFiles.forEach(function(fileName) { - var sourcePath = fs.statSync(filePath).isDirectory() ? filePath : - path.dirname(filePath); - var toDir = fs.toDir( fileName.replace(sourcePath, outdir) ); - fs.mkPath(toDir); - fs.copyFileSync(fileName, toDir); - }); - }); + data().each(function(doclet) { + const url = helper.longnameToUrl[doclet.longname]; + + if (url.indexOf('#') > -1) { + doclet.id = helper.longnameToUrl[doclet.longname].split(/#/).pop(); + } else { + doclet.id = doclet.name; } - if (sourceFilePaths.length) { - sourceFiles = shortenPaths( sourceFiles, path.commonPrefix(sourceFilePaths) ); + if (needsSignature(doclet)) { + addSignatureParams(doclet); + addSignatureReturns(doclet); } - data().each(function(doclet) { - var url = helper.createLink(doclet); - helper.registerLink(doclet.longname, url); + }); - // replace the filename with a shortened version of the full path - var docletPath; - if (doclet.meta) { - docletPath = getPathFromDoclet(doclet); - docletPath = sourceFiles[docletPath].shortened; - if (docletPath) { - doclet.meta.filename = docletPath; - } - } - }); + // do this after the urls have all been generated + data().each(function(doclet) { + doclet.ancestors = getAncestorLinks(doclet); - data().each(function(doclet) { - var url = helper.longnameToUrl[doclet.longname]; - - if (url.indexOf('#') > -1) { - doclet.id = helper.longnameToUrl[doclet.longname].split(/#/).pop(); - } - else { - doclet.id = doclet.name; - } - - if ( needsSignature(doclet) ) { - addSignatureParams(doclet); - addSignatureReturns(doclet); - } - }); - - // do this after the urls have all been generated - data().each(function(doclet) { - doclet.ancestors = getAncestorLinks(doclet); - - if (doclet.kind === 'member') { - addSignatureTypes(doclet); - } - - if (doclet.kind === 'constant') { - addSignatureTypes(doclet); - doclet.kind = 'member'; - } - }); - - var members = helper.getMembers(data); - members.tutorials = tutorials.children; - - // add template helpers - view.find = find; - view.linkto = linkto; - view.resolveAuthorLinks = resolveAuthorLinks; - view.tutoriallink = tutoriallink; - view.htmlsafe = htmlsafe; - view.members = members; //@davidshimjs: To make navigation for customizing - - // once for all - view.nav = buildNav(members); - attachModuleSymbols( find({ kind: ['class', 'function'], longname: {left: 'module:'} }), - members.modules ); - - // only output pretty-printed source files if requested; do this before generating any other - // pages, so the other pages can link to the source files - if (conf['default'].outputSourceFiles) { - generateSourceFiles(sourceFiles); + if (doclet.kind === 'member') { + addSignatureTypes(doclet); } - if (members.globals.length) { generate('Global', [{kind: 'globalobj'}], globalUrl); } + if (doclet.kind === 'constant') { + addSignatureTypes(doclet); + doclet.kind = 'member'; + } + }); - // index page displays information from package.json and lists files - var files = find({kind: 'file'}); + const members = helper.getMembers(data); + members.tutorials = tutorials.children; - generate('Index', - [{kind: 'mainpage', readme: opts.readme, longname: (opts.mainpagetitle) ? opts.mainpagetitle : 'Main Page'}].concat(files), + // add template helpers + view.find = find; + view.linkto = linkto; + view.resolveAuthorLinks = resolveAuthorLinks; + view.tutoriallink = tutoriallink; + view.htmlsafe = htmlsafe; + view.members = members; //@davidshimjs: To make navigation for customizing + + // once for all + view.nav = buildNav(members); + attachModuleSymbols(find({kind: ['class', 'function'], longname: {left: 'module:'}}), + members.modules); + + // only output pretty-printed source files if requested; do this before generating any other + // pages, so the other pages can link to the source files + if (conf['default'].outputSourceFiles) { + generateSourceFiles(sourceFiles); + } + + if (members.globals.length) { + generate('Global', [{kind: 'globalobj'}], globalUrl); + } + + // index page displays information from package.json and lists files + const files = find({kind: 'file'}); + + generate('Index', + [{kind: 'mainpage', readme: opts.readme, longname: (opts.mainpagetitle) ? opts.mainpagetitle : 'Main Page'}].concat(files), indexUrl); - // set up the lists that we'll use to generate pages - var classes = taffy(members.classes); - var modules = taffy(members.modules); - var namespaces = taffy(members.namespaces); - var mixins = taffy(members.mixins); - var externals = taffy(members.externals); + // set up the lists that we'll use to generate pages + const classes = taffy(members.classes); + const modules = taffy(members.modules); + const namespaces = taffy(members.namespaces); + const mixins = taffy(members.mixins); + const externals = taffy(members.externals); - for (var longname in helper.longnameToUrl) { - if ( hasOwnProp.call(helper.longnameToUrl, longname) ) { - var myClasses = helper.find(classes, {longname: longname}); - if (myClasses.length) { - generate('Class: ' + myClasses[0].name, myClasses, helper.longnameToUrl[longname]); - } + for (const longname in helper.longnameToUrl) { + if (hasOwnProp.call(helper.longnameToUrl, longname)) { + const myClasses = helper.find(classes, {longname: longname}); + if (myClasses.length) { + generate('Class: ' + myClasses[0].name, myClasses, helper.longnameToUrl[longname]); + } - var myModules = helper.find(modules, {longname: longname}); - if (myModules.length) { - generate('Module: ' + myModules[0].name, myModules, helper.longnameToUrl[longname]); - } + const myModules = helper.find(modules, {longname: longname}); + if (myModules.length) { + generate('Module: ' + myModules[0].name, myModules, helper.longnameToUrl[longname]); + } - var myNamespaces = helper.find(namespaces, {longname: longname}); - if (myNamespaces.length) { - generate('Namespace: ' + myNamespaces[0].name, myNamespaces, helper.longnameToUrl[longname]); - } + const myNamespaces = helper.find(namespaces, {longname: longname}); + if (myNamespaces.length) { + generate('Namespace: ' + myNamespaces[0].name, myNamespaces, helper.longnameToUrl[longname]); + } - var myMixins = helper.find(mixins, {longname: longname}); - if (myMixins.length) { - generate('Mixin: ' + myMixins[0].name, myMixins, helper.longnameToUrl[longname]); - } + const myMixins = helper.find(mixins, {longname: longname}); + if (myMixins.length) { + generate('Mixin: ' + myMixins[0].name, myMixins, helper.longnameToUrl[longname]); + } - var myExternals = helper.find(externals, {longname: longname}); - if (myExternals.length) { - generate('External: ' + myExternals[0].name, myExternals, helper.longnameToUrl[longname]); - } - } + const myExternals = helper.find(externals, {longname: longname}); + if (myExternals.length) { + generate('External: ' + myExternals[0].name, myExternals, helper.longnameToUrl[longname]); + } } + } - // TODO: move the tutorial functions to templateHelper.js - function generateTutorial(title, tutorial, filename) { - var tutorialData = { - title: title, - header: tutorial.title, - content: tutorial.parse(), - children: tutorial.children - }; + // TODO: move the tutorial functions to templateHelper.js + function generateTutorial(title, tutorial, filename) { + const tutorialData = { + title: title, + header: tutorial.title, + content: tutorial.parse(), + children: tutorial.children + }; - var tutorialPath = path.join(outdir, filename), - html = view.render('tutorial.tmpl', tutorialData); + let html = view.render('tutorial.tmpl', tutorialData); + // yes, you can use {@link} in tutorials too! + html = helper.resolveLinks(html); // turn {@link foo} into foo - // yes, you can use {@link} in tutorials too! - html = helper.resolveLinks(html); // turn {@link foo} into foo + const tutorialPath = path.join(outdir, filename); + fs.writeFileSync(tutorialPath, html, 'utf8'); + } - fs.writeFileSync(tutorialPath, html, 'utf8'); - } - - // tutorials can have only one parent so there is no risk for loops - function saveChildren(node) { - node.children.forEach(function(child) { - generateTutorial('Tutorial: ' + child.title, child, helper.tutorialToUrl(child.name)); - saveChildren(child); - }); - } - saveChildren(tutorials); + // tutorials can have only one parent so there is no risk for loops + function saveChildren(node) { + node.children.forEach(function(child) { + generateTutorial('Tutorial: ' + child.title, child, helper.tutorialToUrl(child.name)); + saveChildren(child); + }); + } + saveChildren(tutorials); }; diff --git a/config/jsdoc/info/define-plugin.js b/config/jsdoc/info/define-plugin.js index 57c4e355f2..78634499ba 100644 --- a/config/jsdoc/info/define-plugin.js +++ b/config/jsdoc/info/define-plugin.js @@ -6,7 +6,7 @@ */ -var DEFAULT_VALUE = /default\s+is\s+`?(true|false)`?/i; +const DEFAULT_VALUE = /default\s+is\s+`?(true|false)`?/i; /** @@ -19,9 +19,9 @@ exports.defineTags = function(dictionary) { canHaveType: true, mustHaveValue: true, onTagged: function(doclet, tag) { - var types = tag.value.type.names; + const types = tag.value.type.names; if (types.length === 1 && types[0] === 'boolean') { - var match = tag.value.description.match(DEFAULT_VALUE); + const match = tag.value.description.match(DEFAULT_VALUE); if (match) { doclet.define = { default: match[1] === 'true' diff --git a/config/jsdoc/info/virtual-plugin.js b/config/jsdoc/info/virtual-plugin.js index 52cc894cef..9209724c27 100644 --- a/config/jsdoc/info/virtual-plugin.js +++ b/config/jsdoc/info/virtual-plugin.js @@ -4,7 +4,7 @@ */ exports.defineTags = function(dictionary) { - var classTag = dictionary.lookUp('class'); + const classTag = dictionary.lookUp('class'); dictionary.defineTag('interface', { mustHaveValue: false, onTagged: function(doclet, tag) { diff --git a/package.json b/package.json index aea273bf03..ef417cad92 100644 --- a/package.json +++ b/package.json @@ -9,7 +9,7 @@ ], "homepage": "https://openlayers.org/", "scripts": { - "lint": "eslint tasks test src/ol examples", + "lint": "eslint tasks test src/ol examples config", "pretest": "npm run lint", "posttest": "npm run typecheck", "test": "npm run karma -- --single-run",