diff --git a/packages/jsdoc-doclet/lib/augment.js b/packages/jsdoc-doclet/lib/augment.js index 21eb5694..a900925d 100644 --- a/packages/jsdoc-doclet/lib/augment.js +++ b/packages/jsdoc-doclet/lib/augment.js @@ -13,6 +13,7 @@ See the License for the specific language governing permissions and limitations under the License. */ + /** * Provides methods for augmenting the parse results based on their content. */ @@ -458,12 +459,12 @@ function getImplementedAdditions(implDoclets, docletStore) { return additions; } -function augment(docletStore, propertyName, docletFinder, jsdocDeps) { +function augment(docletStore, propertyName, docletFinder, env) { const dependencies = sort(mapDependencies(docletStore.docletsByLongname, propertyName)); dependencies.forEach((depName) => { const depDoclets = Array.from(docletStore.docletsByLongname.get(depName) || []); - const additions = docletFinder(depDoclets, docletStore, jsdocDeps); + const additions = docletFinder(depDoclets, docletStore, env); additions.forEach((addition) => { docletStore.add(addition); diff --git a/packages/jsdoc-doclet/lib/borrow.js b/packages/jsdoc-doclet/lib/borrow.js index 819bc16d..fa6ec2c6 100644 --- a/packages/jsdoc-doclet/lib/borrow.js +++ b/packages/jsdoc-doclet/lib/borrow.js @@ -13,6 +13,7 @@ See the License for the specific language governing permissions and limitations under the License. */ + /** * Functions that resolve `@borrows` tags in JSDoc comments. */ @@ -32,10 +33,7 @@ function cloneBorrowedDoclets({ borrowed, longname }, docletStore) { if (borrowedDoclets) { borrowedAs = borrowedAs.replace(/^prototype\./, SCOPE.PUNC.INSTANCE); borrowedDoclets.forEach((borrowedDoclet) => { - const clone = combineDoclets( - borrowedDoclet, - Doclet.emptyDoclet(borrowedDoclet.dependencies) - ); + const clone = combineDoclets(borrowedDoclet, Doclet.emptyDoclet(borrowedDoclet.env)); // TODO: this will fail on longnames like '"Foo#bar".baz' parts = borrowedAs.split(SCOPE.PUNC.INSTANCE); diff --git a/packages/jsdoc-doclet/lib/doclet-store.js b/packages/jsdoc-doclet/lib/doclet-store.js index 0c253a01..3b20fdaf 100644 --- a/packages/jsdoc-doclet/lib/doclet-store.js +++ b/packages/jsdoc-doclet/lib/doclet-store.js @@ -13,6 +13,7 @@ See the License for the specific language governing permissions and limitations under the License. */ + import { dirname, join } from 'node:path'; import { name } from '@jsdoc/core'; @@ -70,9 +71,9 @@ export class DocletStore { DocletStore.#propertiesWithSets.map((prop) => [prop, 'docletsWith' + _.capitalize(prop)]) ); - constructor(dependencies) { + constructor(env) { this.#commonPathPrefix = null; - this.#emitter = dependencies.get('emitter'); + this.#emitter = env.emitter; this.#isListening = false; this.#sourcePaths = new Map(); diff --git a/packages/jsdoc-doclet/lib/doclet.js b/packages/jsdoc-doclet/lib/doclet.js index 81573afe..f8fdff3c 100644 --- a/packages/jsdoc-doclet/lib/doclet.js +++ b/packages/jsdoc-doclet/lib/doclet.js @@ -13,6 +13,7 @@ See the License for the specific language governing permissions and limitations under the License. */ + import path from 'node:path'; import { astNode, Syntax } from '@jsdoc/ast'; @@ -410,9 +411,9 @@ function copySpecificProperties(primary, secondary, target, include) { * doclets. */ export function combineDoclets(primary, secondary) { - const copyMostPropertiesExclude = ['dependencies', 'params', 'properties', 'undocumented']; + const copyMostPropertiesExclude = ['env', 'params', 'properties', 'undocumented']; const copySpecificPropertiesInclude = ['params', 'properties']; - const target = new Doclet('', null, secondary.dependencies); + const target = new Doclet('', null, secondary.env); // First, copy most properties to the target doclet. copyMostProperties(primary, secondary, target, copyMostPropertiesExclude); @@ -449,23 +450,23 @@ Doclet = class { * * @param {string} docletSrc - The raw source code of the jsdoc comment. * @param {object} meta - Properties describing the code related to this comment. - * @param {object} dependencies - JSDoc dependencies. + * @param {object} env - JSDoc environment. */ - constructor(docletSrc, meta, dependencies) { - const accessConfig = dependencies.get('config')?.opts?.access?.slice() ?? []; - const emitter = dependencies.get('emitter'); + constructor(docletSrc, meta, env) { + const accessConfig = env.config?.opts?.access?.slice() ?? []; + const emitter = env.emitter; const boundDefineWatchableProp = defineWatchableProp.bind(null, this); const boundEmitDocletChanged = emitDocletChanged.bind(null, emitter, this); let newTags = []; - this.#dictionary = dependencies.get('tags'); + this.#dictionary = env.tags; Object.defineProperty(this, 'accessConfig', { value: accessConfig, writable: true, }); - Object.defineProperty(this, 'dependencies', { - value: dependencies, + Object.defineProperty(this, 'env', { + value: env, }); Object.defineProperty(this, 'watchableProps', { value: {}, @@ -518,11 +519,11 @@ Doclet = class { } static clone(doclet) { - return combineDoclets(doclet, Doclet.emptyDoclet(doclet.dependencies)); + return combineDoclets(doclet, Doclet.emptyDoclet(doclet.env)); } - static emptyDoclet(dependencies) { - return new Doclet('', {}, dependencies); + static emptyDoclet(env) { + return new Doclet('', {}, env); } // TODO: We call this method in the constructor _and_ in `jsdoc/src/handlers`. It appears that @@ -566,7 +567,7 @@ Doclet = class { */ addTag(title, text) { const tagDef = this.#dictionary.lookUp(title); - const newTag = new Tag(title, text, this.meta, this.dependencies); + const newTag = new Tag(title, text, this.meta, this.env); if (tagDef && tagDef.onTagged) { tagDef.onTagged(this, newTag); diff --git a/packages/jsdoc-doclet/lib/package.js b/packages/jsdoc-doclet/lib/package.js index 89e20fee..0528cca1 100644 --- a/packages/jsdoc-doclet/lib/package.js +++ b/packages/jsdoc-doclet/lib/package.js @@ -79,10 +79,10 @@ function getLicenses(packageInfo) { export class Package { /** * @param {string} json - The contents of the `package.json` file. - * @param {Object} deps - The JSDoc dependencies. + * @param {Object} env - The JSDoc environment. */ - constructor(json, deps) { - const log = deps.get('log'); + constructor(json, env) { + const log = env.log; let packageInfo; /** diff --git a/packages/jsdoc-doclet/test/specs/lib/doclet-store.js b/packages/jsdoc-doclet/test/specs/lib/doclet-store.js index 03795360..d723e557 100644 --- a/packages/jsdoc-doclet/test/specs/lib/doclet-store.js +++ b/packages/jsdoc-doclet/test/specs/lib/doclet-store.js @@ -59,7 +59,7 @@ describe('@jsdoc/doclet/lib/doclet-store', () => { expect(() => new DocletStore()).toThrow(); }); - it('is constructable when dependencies are passed in', () => { + it('is constructable when JSDoc environment is passed in', () => { expect(() => new DocletStore(jsdoc.env)).not.toThrow(); }); diff --git a/packages/jsdoc-tag/lib/definitions/closure.js b/packages/jsdoc-tag/lib/definitions/closure.js index e13e8f98..dc332ed5 100644 --- a/packages/jsdoc-tag/lib/definitions/closure.js +++ b/packages/jsdoc-tag/lib/definitions/closure.js @@ -13,6 +13,7 @@ See the License for the specific language governing permissions and limitations under the License. */ + // Tag dictionary for Google Closure Compiler. import { getTags as getCoreTags } from './core.js'; @@ -24,8 +25,8 @@ const NOOP_TAG = { }, }; -export const getTags = (deps) => { - const coreTags = getCoreTags(deps); +export const getTags = (env) => { + const coreTags = getCoreTags(env); return { const: { diff --git a/packages/jsdoc-tag/lib/definitions/core.js b/packages/jsdoc-tag/lib/definitions/core.js index 460d97d5..bb6e3495 100644 --- a/packages/jsdoc-tag/lib/definitions/core.js +++ b/packages/jsdoc-tag/lib/definitions/core.js @@ -13,6 +13,7 @@ See the License for the specific language governing permissions and limitations under the License. */ + import { astNode, Syntax } from '@jsdoc/ast'; import { name } from '@jsdoc/core'; @@ -29,7 +30,7 @@ function stripModuleNamespace(docletName) { } // Core JSDoc tags that are shared with other tag dictionaries. -export const getTags = (deps) => ({ +export const getTags = (env) => ({ abstract: { mustNotHaveValue: true, onTagged(doclet) { @@ -296,12 +297,12 @@ export const getTags = (deps) => ({ }, inner: { onTagged(doclet, tag) { - util.setDocletScopeToTitle(doclet, tag, deps); + util.setDocletScopeToTitle(doclet, tag, env); }, }, instance: { onTagged(doclet, tag) { - util.setDocletScopeToTitle(doclet, tag, deps); + util.setDocletScopeToTitle(doclet, tag, env); }, }, interface: { @@ -495,7 +496,7 @@ export const getTags = (deps) => ({ }, static: { onTagged(doclet, tag) { - util.setDocletScopeToTitle(doclet, tag, deps); + util.setDocletScopeToTitle(doclet, tag, env); }, }, summary: { diff --git a/packages/jsdoc-tag/lib/definitions/util.js b/packages/jsdoc-tag/lib/definitions/util.js index e2bf5e4a..3021bf27 100644 --- a/packages/jsdoc-tag/lib/definitions/util.js +++ b/packages/jsdoc-tag/lib/definitions/util.js @@ -74,13 +74,10 @@ export function setDocletKindToTitle(doclet, { title }) { doclet.addTag('kind', title); } -export function setDocletScopeToTitle(doclet, { title }, deps) { - let log; - +export function setDocletScopeToTitle(doclet, { title }, { log }) { try { doclet.setScope(title); } catch (e) { - log = deps.get('log'); log.error(e.message); } } @@ -123,8 +120,7 @@ export function setNameToFile(doclet) { let docletName; if (doclet.meta.filename) { - docletName = - filepathMinusPrefix(doclet.meta.path, doclet.dependencies.get('env')) + doclet.meta.filename; + docletName = filepathMinusPrefix(doclet.meta.path, doclet.env) + doclet.meta.filename; doclet.addTag('name', docletName); } } @@ -153,7 +149,7 @@ export function setDocletNameToFilename(doclet) { let docletName = ''; if (doclet.meta.path) { - docletName = filepathMinusPrefix(doclet.meta.path, doclet.dependencies.get('env')); + docletName = filepathMinusPrefix(doclet.meta.path, doclet.env); } // TODO: Drop the file extension regardless of what it is. docletName += doclet.meta.filename.replace(/\.js$/i, ''); diff --git a/packages/jsdoc-template-legacy/lib/templateHelper.js b/packages/jsdoc-template-legacy/lib/templateHelper.js index b66e84a3..0064b44f 100644 --- a/packages/jsdoc-template-legacy/lib/templateHelper.js +++ b/packages/jsdoc-template-legacy/lib/templateHelper.js @@ -13,6 +13,7 @@ See the License for the specific language governing permissions and limitations under the License. */ + import { name } from '@jsdoc/core'; import { inline } from '@jsdoc/tag'; import catharsis from 'catharsis'; @@ -60,8 +61,8 @@ function getNamespace(kind, dictionary) { return ''; } -function formatNameForLink(doclet, dependencies) { - const dictionary = dependencies.get('tags'); +function formatNameForLink(doclet, env) { + const dictionary = env.tags; let newName = getNamespace(doclet.kind, dictionary) + (doclet.name || '') + (doclet.variation || ''); const scopePunc = SCOPE_TO_PUNC[doclet.scope] || ''; @@ -112,11 +113,11 @@ function makeUniqueFilename(filename, str) { * * @function * @param {string} str The string to convert. - * @param {Object} dependencies The JSDoc dependency container. + * @param {Object} env The JSDoc environment. * @return {string} The filename to use for the string. */ -export function getUniqueFilename(str, dependencies) { - const dictionary = dependencies.get('tags'); +export function getUniqueFilename(str, env) { + const dictionary = env.tags; const namespaces = dictionary.getNamespaces().join('|'); let basename = (str || '') // use - instead of : in namespace prefixes @@ -145,13 +146,13 @@ export function getUniqueFilename(str, dependencies) { * register the filename. * @private */ -function getFilename(longname, dependencies) { +function getFilename(longname, env) { let fileUrl; if (Object.hasOwn(longnameToUrl, longname)) { fileUrl = longnameToUrl[longname]; } else { - fileUrl = getUniqueFilename(longname, dependencies); + fileUrl = getUniqueFilename(longname, env); registerLink(longname, fileUrl); } @@ -379,9 +380,9 @@ export function linkto(longname, linkText, cssClass, fragmentId) { }); } -function useMonospace(tag, text, dependencies) { +function useMonospace(tag, text, env) { let cleverLinks; - const config = dependencies.get('config'); + const config = env.config; let monospaceLinks; let result; @@ -434,8 +435,8 @@ function splitLinkText(text) { }; } -function shouldShortenLongname(dependencies) { - const config = dependencies.get('config'); +function shouldShortenLongname(env) { + const config = env.config; if (config && config.templates && config.templates.useShortNamesInLinks) { return true; @@ -448,10 +449,10 @@ function shouldShortenLongname(dependencies) { * Find `{@link ...}` inline tags and turn them into HTML links. * * @param {string} str - The string to search for `{@link ...}` tags. - * @param {object} dependencies - The JSDoc dependencies container. + * @param {object} env - The JSDoc environment. * @return {string} The linkified text. */ -export function resolveLinks(str, dependencies) { +export function resolveLinks(str, env) { let replacers; function extractLeadingText(string, completeTag) { @@ -490,14 +491,14 @@ export function resolveLinks(str, dependencies) { target = split.target; linkText = linkText || split.linkText; - monospace = useMonospace(tag, text, dependencies); + monospace = useMonospace(tag, text, env); return string.replace( completeTag, buildLink(target, linkText, { linkMap: longnameToUrl, monospace: monospace, - shortenName: shouldShortenLongname(dependencies), + shortenName: shouldShortenLongname(env), }) ); } @@ -832,11 +833,11 @@ export function addEventListeners(data) { * + Members tagged `@private`, unless the `private` option is enabled. * + Members tagged with anything other than specified by the `access` options. * @param {TAFFY} data The TaffyDB database to prune. - * @param {object} dependencies The JSDoc dependencies container. + * @param {object} env The JSDoc environment. * @return {TAFFY} The pruned database. */ -export function prune(data, dependencies) { - const options = dependencies.get('options'); +export function prune(data, env) { + const options = env.options; data({ undocumented: true }).remove(); data({ ignore: true }).remove(); @@ -876,10 +877,10 @@ export function prune(data, dependencies) { * represents a method), the URL will consist of a filename and a fragment ID. * * @param {module:@jsdoc/doclet.Doclet} doclet - The doclet that will be used to create the URL. - * @param {Object} dependencies - The JSDoc dependency container. + * @param {Object} env - The JSDoc environment. * @return {string} The URL to the generated documentation for the doclet. */ -export function createLink(doclet, dependencies) { +export function createLink(doclet, env) { let fakeContainer; let filename; let fileUrl; @@ -900,21 +901,21 @@ export function createLink(doclet, dependencies) { // the doclet gets its own HTML file if (containers.includes(doclet.kind) || isModuleExports(doclet)) { - filename = getFilename(longname, dependencies); + filename = getFilename(longname, env); } // mistagged version of a doclet that gets its own HTML file else if (!containers.includes(doclet.kind) && fakeContainer) { - filename = getFilename(doclet.memberof || longname, dependencies); + filename = getFilename(doclet.memberof || longname, env); if (doclet.name !== doclet.longname) { - fragment = formatNameForLink(doclet, dependencies); + fragment = formatNameForLink(doclet, env); fragment = getId(longname, fragment); } } // the doclet is within another HTML file else { - filename = getFilename(doclet.memberof || globalName, dependencies); + filename = getFilename(doclet.memberof || globalName, env); if (doclet.name !== doclet.longname || doclet.scope === SCOPE.NAMES.GLOBAL) { - fragment = formatNameForLink(doclet, dependencies); + fragment = formatNameForLink(doclet, env); fragment = getId(longname, fragment); } } diff --git a/packages/jsdoc-template-legacy/test/specs/lib/templateHelper.js b/packages/jsdoc-template-legacy/test/specs/lib/templateHelper.js index 7b7a824e..729cdf68 100644 --- a/packages/jsdoc-template-legacy/test/specs/lib/templateHelper.js +++ b/packages/jsdoc-template-legacy/test/specs/lib/templateHelper.js @@ -1588,7 +1588,7 @@ describe('@jsdoc/template-legacy/lib/templateHelper', () => { describe('createLink', () => { it('should create a url for a simple global.', () => { const mockDoclet = { - dependencies: jsdoc.env, + env: jsdoc.env, kind: 'function', longname: 'foo', name: 'foo', @@ -1601,7 +1601,7 @@ describe('@jsdoc/template-legacy/lib/templateHelper', () => { it('should create a url for a namespace.', () => { const mockDoclet = { - dependencies: jsdoc.env, + env: jsdoc.env, kind: 'namespace', longname: 'foo', name: 'foo', @@ -1613,7 +1613,7 @@ describe('@jsdoc/template-legacy/lib/templateHelper', () => { it('should create a url for a member of a namespace.', () => { const mockDoclet = { - dependencies: jsdoc.env, + env: jsdoc.env, kind: 'function', longname: 'ns.foo', name: 'foo', @@ -1625,7 +1625,7 @@ describe('@jsdoc/template-legacy/lib/templateHelper', () => { }); const nestedNamespaceDoclet = { - dependencies: jsdoc.env, + env: jsdoc.env, kind: 'function', longname: 'ns1.ns2.foo', name: 'foo', @@ -1647,7 +1647,7 @@ describe('@jsdoc/template-legacy/lib/templateHelper', () => { it('should create a url for a name with invalid characters.', () => { const mockDoclet = { - dependencies: jsdoc.env, + env: jsdoc.env, kind: 'function', longname: 'ns1."!"."*foo"', name: '"*foo"', @@ -1660,7 +1660,7 @@ describe('@jsdoc/template-legacy/lib/templateHelper', () => { it('should create a url for a function that is the only symbol exported by a module.', () => { const mockDoclet = { - dependencies: jsdoc.env, + env: jsdoc.env, kind: 'function', longname: 'module:bar', name: 'module:bar', @@ -1672,13 +1672,13 @@ describe('@jsdoc/template-legacy/lib/templateHelper', () => { it('should create a url for a doclet with the wrong kind (caused by incorrect JSDoc tags', () => { const moduleDoclet = { - dependencies: jsdoc.env, + env: jsdoc.env, kind: 'module', longname: 'module:baz', name: 'module:baz', }; const badDoclet = { - dependencies: jsdoc.env, + env: jsdoc.env, kind: 'member', longname: 'module:baz', name: 'module:baz', @@ -1692,13 +1692,13 @@ describe('@jsdoc/template-legacy/lib/templateHelper', () => { it('should create a url for a function that is a member of a doclet with the wrong kind', () => { const badModuleDoclet = { - dependencies: jsdoc.env, + env: jsdoc.env, kind: 'member', longname: 'module:qux', name: 'module:qux', }; const memberDoclet = { - dependencies: jsdoc.env, + env: jsdoc.env, kind: 'function', name: 'frozzle', memberof: 'module:qux', @@ -1714,7 +1714,7 @@ describe('@jsdoc/template-legacy/lib/templateHelper', () => { it('should include the scope punctuation in the fragment ID for static members', () => { const functionDoclet = { - dependencies: jsdoc.env, + env: jsdoc.env, kind: 'function', longname: 'Milk.pasteurize', name: 'pasteurize', @@ -1728,7 +1728,7 @@ describe('@jsdoc/template-legacy/lib/templateHelper', () => { it('should include the scope punctuation in the fragment ID for inner members', () => { const functionDoclet = { - dependencies: jsdoc.env, + env: jsdoc.env, kind: 'function', longname: 'Milk~removeSticksAndLeaves', name: 'removeSticksAndLeaves', @@ -1742,7 +1742,7 @@ describe('@jsdoc/template-legacy/lib/templateHelper', () => { it('should omit the scope punctuation from the fragment ID for instance members', () => { const propertyDoclet = { - dependencies: jsdoc.env, + env: jsdoc.env, kind: 'member', longname: 'Milk#calcium', name: 'calcium', @@ -1756,7 +1756,7 @@ describe('@jsdoc/template-legacy/lib/templateHelper', () => { it('should include the variation, if present, in the fragment ID', () => { const variationDoclet = { - dependencies: jsdoc.env, + env: jsdoc.env, kind: 'function', longname: 'Milk#fat(percent)', name: 'fat',