archive-gh-me/jsdoc
1
0
Fork 0
mirror of https://github.com/jsdoc/jsdoc.git synced 2025-12-08 19:46:11 +00:00
Code Issues Projects Releases Wiki Activity

refactor(jsdoc): remove jsdoc/path module

Browse Source 
BREAKING CHANGE: The `jsdoc/path` module was removed. Use `path` instead.
This commit is contained in:
Jeff Williams 2019-12-02 20:49:38 -08:00
parent ca7a33f68b
commit eb32943204
26 changed files with 42 additions and 255 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
package-lock.json generated
View File

@ -5803,9 +5803,9 @@
}
},
"handlebars": {
"version": "4.3.1",
"resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.3.1.tgz",
"integrity": "sha512-c0HoNHzDiHpBt4Kqe99N8tdLPKAnGCQ73gYMPWtAYM4PwGnf7xl8PBUHJqh9ijlzt2uQKaSRxbXRt+rZ7M2/kA==",
"version": "4.5.3",
"resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.5.3.tgz",
"integrity": "sha512-3yPecJoJHK/4c6aZhSvxOyG4vJKDshV36VHp0iVCDVh7o9w2vwi3NSnL2MMPj3YdduqaBcu7cGbggJQM0br9xA==",
"dev": true,
"requires": {
"neo-async": "^2.6.0",

2
packages/jsdoc/lib/jsdoc/doclet.js
View File

@ -5,7 +5,7 @@ const _ = require('lodash');
let dictionary = require('jsdoc/tag/dictionary');
const { isFunction } = require('jsdoc/src/astnode');
const name = require('jsdoc/name');
const path = require('jsdoc/path');
const path = require('path');
const { Syntax } = require('jsdoc/src/syntax');
const { Tag } = require('jsdoc/tag');

81
packages/jsdoc/lib/jsdoc/path.js
View File

@ -1,81 +0,0 @@
/**
* Extended version of the standard `path` module.
* @module jsdoc/path
*/
const env = require('jsdoc/env');
const path = require('path');
function prefixReducer(previousPath, current) {
let currentPath = [];
// if previousPath is defined, but has zero length, there's no common prefix; move along
if (previousPath && !previousPath.length) {
return currentPath;
}
currentPath = path.resolve(env.pwd, current).split(path.sep) || [];
if (previousPath && currentPath.length) {
// remove chunks that exceed the previous path's length
currentPath = currentPath.slice(0, previousPath.length);
// if a chunk doesn't match the previous path, remove everything from that chunk on
for (let i = 0, l = currentPath.length; i < l; i++) {
if (currentPath[i] !== previousPath[i]) {
currentPath.splice(i, currentPath.length - i);
break;
}
}
}
return currentPath;
}
/**
* Find the common prefix for an array of paths. If there is a common prefix, a trailing separator
* is appended to the prefix. Relative paths are resolved relative to the current working directory.
*
* For example, assuming that the current working directory is `/Users/jsdoc`:
*
* + For the single path `foo/bar/baz/qux.js`, the common prefix is `foo/bar/baz/`.
* + For paths `foo/bar/baz/qux.js`, `foo/bar/baz/quux.js`, and `foo/bar/baz.js`, the common prefix
* is `/Users/jsdoc/foo/bar/`.
* + For paths `../jsdoc/foo/bar/baz/qux/quux/test.js`, `/Users/jsdoc/foo/bar/bazzy.js`, and
* `../../Users/jsdoc/foo/bar/foobar.js`, the common prefix is `/Users/jsdoc/foo/bar/`.
* + For paths `foo/bar/baz/qux.js` and `../../Library/foo/bar/baz.js`, there is no common prefix,
* and an empty string is returned.
*
* @param {Array.<string>} paths - The paths to search for a common prefix.
* @return {string} The common prefix, or an empty string if there is no common prefix.
*/
exports.commonPrefix = (paths = []) => {
let prefix = '';
let segments;
// if there's only one path, its resolved dirname (plus a trailing slash) is the common prefix
if (paths.length === 1) {
prefix = path.resolve(env.pwd, paths[0]);
if ( path.extname(prefix) ) {
prefix = path.dirname(prefix);
}
prefix += path.sep;
}
else {
segments = paths.reduce(prefixReducer, undefined) || [];
// if there's anything left (other than a placeholder for a leading slash), add a
// placeholder for a trailing slash
if ( segments.length && (segments.length > 1 || segments[0] !== '') ) {
segments.push('');
}
prefix = segments.join(path.sep);
}
return prefix;
};
Object.keys(path).forEach(member => {
exports[member] = path[member];
});

2
packages/jsdoc/lib/jsdoc/src/filter.js
View File

@ -2,7 +2,7 @@
* @module jsdoc/src/filter
*/
const env = require('jsdoc/env');
const path = require('jsdoc/path');
const path = require('path');
function makeRegExp(config) {
let regExp = null;

2
packages/jsdoc/lib/jsdoc/src/scanner.js
View File

@ -6,7 +6,7 @@ const { EventEmitter } = require('events');
const env = require('jsdoc/env');
const fs = require('jsdoc/fs');
const logger = require('jsdoc/util/logger');
const path = require('jsdoc/path');
const path = require('path');
/**
* @extends module:events.EventEmitter

9
packages/jsdoc/lib/jsdoc/tag.js
View File

@ -1,17 +1,10 @@
/**
* Functionality related to JSDoc tags.
* @module jsdoc/tag
* @requires module:jsdoc/env
* @requires module:jsdoc/path
* @requires module:jsdoc/tag/dictionary
* @requires module:jsdoc/tag/validator
* @requires module:jsdoc/tag/type
* @requires module:jsdoc/util/logger
* @requires module:util
*/
const env = require('jsdoc/env');
const logger = require('jsdoc/util/logger');
const path = require('jsdoc/path');
const path = require('path');
const tag = {
dictionary: require('jsdoc/tag/dictionary'),
validator: require('jsdoc/tag/validator'),

9
packages/jsdoc/lib/jsdoc/tag/dictionary/definitions.js
View File

@ -3,12 +3,13 @@
* @module jsdoc/tag/dictionary/definitions
*/
const _ = require('lodash');
const commonPathPrefix = require('common-path-prefix');
const env = require('jsdoc/env');
const { isInlineTag } = require('jsdoc/tag/inline');
const logger = require('jsdoc/util/logger');
const name = require('jsdoc/name');
const { nodeToValue } = require('jsdoc/src/astnode');
const path = require('jsdoc/path');
const path = require('path');
const { Syntax } = require('jsdoc/src/syntax');
const parseTagType = require('jsdoc/tag/type').parse;
@ -46,10 +47,14 @@ function getSourcePaths() {
}
function filepathMinusPrefix(filepath) {
let commonPrefix;
const sourcePaths = getSourcePaths();
const commonPrefix = path.commonPrefix(sourcePaths);
let result = '';
commonPrefix = sourcePaths.length > 1 ?
commonPathPrefix(sourcePaths) :
path.dirname(sourcePaths[0] || '') + path.sep;
if (filepath) {
filepath = path.normalize(filepath);
// always use forward slashes in the result

5
packages/jsdoc/package-lock.json generated
View File

@ -40,6 +40,11 @@
"resolved": "https://registry.npmjs.org/color-themes-for-google-code-prettify/-/color-themes-for-google-code-prettify-2.0.4.tgz",
"integrity": "sha1-3urPZX/WhXaGR1TU5IbXjf2x54Q="
},
"common-path-prefix": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/common-path-prefix/-/common-path-prefix-3.0.0.tgz",
"integrity": "sha512-QE33hToZseCH3jS0qN96O/bSh3kaw/h+Tq7ngyY9eWDUnTlTNUyqfqvCXioLe5Na5jFsL78ra/wuBU4iuEgd4w=="
},
"entities": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/entities/-/entities-2.0.0.tgz",

1
packages/jsdoc/package.json
View File

@ -20,6 +20,7 @@
"catharsis": "^0.8.11",
"code-prettify": "^0.1.0",
"color-themes-for-google-code-prettify": "^2.0.4",
"common-path-prefix": "^3.0.0",
"escape-string-regexp": "^2.0.0",
"lodash": "^4.17.15",
"markdown-it": "^10.0.0",

2
packages/jsdoc/plugins/test/specs/commentConvert.js
View File

@ -2,7 +2,7 @@
describe('commentConvert plugin', () => {
const env = require('jsdoc/env');
const path = require('jsdoc/path');
const path = require('path');
let docSet;
const parser = jsdoc.createParser();

2
packages/jsdoc/plugins/test/specs/escapeHtml.js
View File

@ -1,7 +1,7 @@
/* global jsdoc */
describe('escapeHtml plugin', () => {
const env = require('jsdoc/env');
const path = require('jsdoc/path');
const path = require('path');
let docSet;
const parser = jsdoc.createParser();

2
packages/jsdoc/plugins/test/specs/markdown.js
View File

@ -1,6 +1,6 @@
/* global jsdoc */
const env = require('jsdoc/env');
const path = require('jsdoc/path');
const path = require('path');
describe('markdown plugin', () => {
const pluginPath = 'plugins/markdown';

2
packages/jsdoc/plugins/test/specs/overloadHelper.js
View File

@ -1,7 +1,7 @@
/* global jsdoc */
describe('plugins/overloadHelper', () => {
const env = require('jsdoc/env');
const path = require('jsdoc/path');
const path = require('path');
let docSet;
const parser = jsdoc.createParser();

2
packages/jsdoc/plugins/test/specs/railsTemplate.js
View File

@ -1,7 +1,7 @@
/* global jsdoc */
describe('railsTemplate plugin', () => {
const env = require('jsdoc/env');
const path = require('jsdoc/path');
const path = require('path');
const parser = jsdoc.createParser();
const pluginPath = path.join(env.dirname, 'plugins/railsTemplate');

2
packages/jsdoc/plugins/test/specs/shout.js
View File

@ -1,7 +1,7 @@
/* global jsdoc */
describe('shout plugin', () => {
const env = require('jsdoc/env');
const path = require('jsdoc/path');
const path = require('path');
let docSet;
const parser = jsdoc.createParser();

2
packages/jsdoc/plugins/test/specs/sourcetag.js
View File

@ -1,7 +1,7 @@
/* global jsdoc */
describe('sourcetag plugin', () => {
const env = require('jsdoc/env');
const path = require('jsdoc/path');
const path = require('path');
let docSet;
const parser = jsdoc.createParser();

2
packages/jsdoc/plugins/test/specs/underscore.js
View File

@ -1,7 +1,7 @@
/* global jsdoc */
describe('underscore plugin', () => {
const env = require('jsdoc/env');
const path = require('jsdoc/path');
const path = require('path');
let docSet;
const parser = jsdoc.createParser();

5
packages/jsdoc/templates/default/publish.js
View File

@ -1,9 +1,10 @@
const _ = require('lodash');
const commonPathPrefix = require('common-path-prefix');
const env = require('jsdoc/env');
const fs = require('jsdoc/fs');
const helper = require('jsdoc/util/templateHelper');
const logger = require('jsdoc/util/logger');
const path = require('jsdoc/path');
const path = require('path');
const { taffy } = require('taffydb');
const template = require('jsdoc/template');
@ -591,7 +592,7 @@ exports.publish = (taffyData, opts, tutorials) => {
}
if (sourceFilePaths.length) {
sourceFiles = shortenPaths( sourceFiles, path.commonPrefix(sourceFilePaths) );
sourceFiles = shortenPaths( sourceFiles, commonPathPrefix(sourceFilePaths) );
}
data().each(doclet => {
let docletPath;

2
packages/jsdoc/test/helpers/jsdoc.js
View File

@ -6,7 +6,7 @@ const dictionary = require('jsdoc/tag/dictionary');
const env = require('jsdoc/env');
const fs = require('jsdoc/fs');
const handlers = require('jsdoc/src/handlers');
const path = require('jsdoc/path');
const path = require('path');
const originalDictionary = dictionary;
const parseResults = [];

18
packages/jsdoc/test/specs/documentation/modules.js
View File

@ -1,13 +1,9 @@
describe('module names', () => {
const env = require('jsdoc/env');
const path = require('jsdoc/path');
const path = require('path');
let doclets;
const pwd = env.pwd;
let srcParser = null;
const sourceFiles = env.sourceFiles.slice(0);
const sourcePaths = env.opts._.slice(0);
beforeEach(() => {
env.opts._ = [path.normalize(`${__dirname}/../../fixtures/modules/data`)];
@ -17,19 +13,11 @@ describe('module names', () => {
require('jsdoc/src/handlers').attachTo(srcParser);
});
afterEach(() => {
env.opts._ = sourcePaths;
env.pwd = pwd;
env.sourceFiles = sourceFiles;
});
it('should create a name from the file path when no documented module name exists', () => {
const filename = 'test/fixtures/modules/data/mod-1.js';
const filename = path.resolve(env.pwd, 'test/fixtures/modules/data/mod-1.js');
env.sourceFiles.push(filename);
doclets = srcParser.parse(
path.normalize( path.join(env.pwd, filename) )
);
doclets = srcParser.parse(filename);
expect(doclets.length).toBeGreaterThan(1);
expect(doclets[0].longname).toBe('module:mod-1');

123
packages/jsdoc/test/specs/jsdoc/path.js
View File

@ -1,123 +0,0 @@
describe('jsdoc/path', () => {
const env = require('jsdoc/env');
const os = require('os');
const path = require('jsdoc/path');
const standardPath = require('path');
const isWindows = /^win/.test( os.platform() );
it('should exist', () => {
expect(path).toBeObject();
});
it('should export all functions in the "path" module', () => {
Object.keys(standardPath).forEach(item => {
if (typeof standardPath[item] === 'function') {
expect(path[item]).toBeFunction();
}
});
});
it('should export a "commonPrefix" function', () => {
expect(path.commonPrefix).toBeFunction();
});
describe('commonPrefix', () => {
let oldPwd;
let cwd;
beforeEach(() => {
oldPwd = env.pwd;
env.pwd = isWindows ? 'C:\\Users\\jsdoc' : '/Users/jsdoc';
cwd = env.pwd.split(path.sep);
});
afterEach(() => {
env.pwd = oldPwd;
});
it('finds the correct prefix for a single relative path', () => {
const paths = [path.join('foo', 'bar', 'baz', 'qux.js')];
// we expect a trailing slash
const expected = cwd.concat('foo', 'bar', 'baz', '').join(path.sep);
expect( path.commonPrefix(paths) ).toBe(expected);
});
it('finds the correct prefix for a group of relative paths', () => {
const paths = [
path.join('foo', 'bar', 'baz', 'qux.js'),
path.join('foo', 'bar', 'baz', 'quux.js'),
path.join('foo', 'bar', 'baz.js')
];
// we expect a trailing slash
const expected = cwd.concat('foo', 'bar', '').join(path.sep);
expect( path.commonPrefix(paths) ).toBe(expected);
});
it('finds the correct prefix for a single absolute path', () => {
const paths = [cwd.concat('foo', 'bar', 'baz', 'qux.js').join(path.sep)];
// we expect a trailing slash
const expected = cwd.concat('foo', 'bar', 'baz', '').join(path.sep);
expect( path.commonPrefix(paths) ).toBe(expected);
});
it('finds the correct prefix for a group of absolute paths', () => {
const paths = [
cwd.concat('foo', 'bar', 'baz', 'qux.js').join(path.sep),
cwd.concat('foo', 'bar', 'baz', 'quux.js').join(path.sep),
cwd.concat('foo', 'bar', 'baz.js').join(path.sep)
];
// we expect a trailing slash
const expected = cwd.concat('foo', 'bar', '').join(path.sep);
expect( path.commonPrefix(paths) ).toBe(expected);
});
it('finds the correct prefix for a group of absolute paths and dotted relative paths',
() => {
const paths = [
path.join('..', 'jsdoc', 'foo', 'bar', 'baz', 'qux', 'quux', 'test.js'),
cwd.concat('foo', 'bar', 'bazzy.js').join(path.sep),
path.join('..', '..', 'Users', 'jsdoc', 'foo', 'bar', 'foobar.js')
];
// we expect a trailing slash
const expected = cwd.concat('foo', 'bar', '').join(path.sep);
expect( path.commonPrefix(paths) ).toBe(expected);
});
it('returns an empty string when the paths array is empty', () => {
const paths = [];
expect( path.commonPrefix(paths) ).toBe('');
});
// skip on Windows, since the paths share a drive letter at the start
if (!isWindows) {
it('returns an empty string when there is no common prefix', () => {
const paths = [
path.join('foo', 'bar', 'baz', 'qux.js'),
path.join('..', '..', 'Library', 'foo', 'bar', 'baz.js')
];
expect( path.commonPrefix(paths) ).toBe('');
});
}
// only test Windows paths on Windows
if (isWindows) {
it('works with Windows paths that contain spaces', () => {
const prefix = 'C:\\Users\\Jane Smith\\myproject\\';
const paths = [
`${prefix}index.js`,
`${prefix}lib\\mymodule.js`
];
expect( path.commonPrefix(paths) ).toBe(prefix);
});
}
});
});

2
packages/jsdoc/test/specs/jsdoc/src/filter.js
View File

@ -1,7 +1,7 @@
describe('jsdoc/src/filter', () => {
const env = require('jsdoc/env');
const filter = require('jsdoc/src/filter');
const path = require('jsdoc/path');
const path = require('path');
it('should exist', () => {
expect(filter).toBeObject();

2
packages/jsdoc/test/specs/jsdoc/src/parser.js
View File

@ -6,7 +6,7 @@ describe('jsdoc/src/parser', () => {
const fs = require('jsdoc/fs');
const jsdocParser = require('jsdoc/src/parser');
const logger = require('jsdoc/util/logger');
const path = require('jsdoc/path');
const path = require('path');
it('should exist', () => {
expect(jsdocParser).toBeObject();

2
packages/jsdoc/test/specs/jsdoc/src/scanner.js
View File

@ -1,5 +1,5 @@
describe('jsdoc/src/scanner', () => {
const path = require('jsdoc/path');
const path = require('path');
const scanner = require('jsdoc/src/scanner');
const filter = new (require('jsdoc/src/filter').Filter)({

2
packages/jsdoc/test/specs/plugins/plugins.js
View File

@ -1,7 +1,7 @@
// TODO: consolidate with specs/jsdoc/parser and specs/jsdoc/plugins
describe('plugins', () => {
const env = require('jsdoc/env');
const path = require('jsdoc/path');
const path = require('path');
let docSet;
const pluginPaths = [

8
packages/jsdoc/test/specs/tags/overviewtag.js
View File

@ -1,6 +1,6 @@
describe('@overview tag', () => {
const env = require('jsdoc/env');
const path = require('jsdoc/path');
const path = require('path');
let doclets;
@ -24,12 +24,10 @@ describe('@overview tag', () => {
});
it('When a file overview tag appears in a doclet, the name of the doclet should contain the path to the file.', () => {
const filename = 'test/fixtures/file.js';
const filename = path.resolve(env.pwd, 'test/fixtures/file.js');
env.sourceFiles.push(filename);
doclets = srcParser.parse(
path.normalize( path.join(env.pwd, filename) )
);
doclets = srcParser.parse(filename);
expect(doclets[0].name).toMatch(/^file\.js$/);
});