brut-js 0.16.0 → 0.18.0

package/docs/node_modules/jsdoc/lib/jsdoc/tag/dictionary/definitions.js

@@ -0,0 +1,1089 @@
+/**
+ * Define tags that are known in JSDoc.
+ * @module jsdoc/tag/dictionary/definitions
+ */
+const _ = require('underscore');
+const jsdoc = {
+    env: require('jsdoc/env'),
+    name: require('jsdoc/name'),
+    src: {
+        astnode: require('jsdoc/src/astnode')
+    },
+    tag: {
+        inline: require('jsdoc/tag/inline'),
+        type: require('jsdoc/tag/type')
+    },
+    util: {
+        doop: require('jsdoc/util/doop'),
+        logger: require('jsdoc/util/logger')
+    }
+};
+const path = require('jsdoc/path');
+const Syntax = require('jsdoc/src/syntax').Syntax;
+
+const hasOwnProp = Object.prototype.hasOwnProperty;
+
+const DEFINITIONS = {
+    closure: 'closureTags',
+    jsdoc: 'jsdocTags'
+};
+const MODULE_NAMESPACE = 'module:';
+
+// Clone a tag definition, excluding synonyms.
+function cloneTagDef(tagDef, extras) {
+    const newTagDef = jsdoc.util.doop(tagDef);
+
+    delete newTagDef.synonyms;
+
+    return (extras ? _.extend(newTagDef, extras) : newTagDef);
+}
+
+function getSourcePaths() {
+    const sourcePaths = jsdoc.env.sourceFiles.slice(0) || [];
+
+    if (jsdoc.env.opts._) {
+        jsdoc.env.opts._.forEach(sourcePath => {
+            const resolved = path.resolve(jsdoc.env.pwd, sourcePath);
+
+            if (!sourcePaths.includes(resolved)) {
+                sourcePaths.push(resolved);
+            }
+        });
+    }
+
+    return sourcePaths;
+}
+
+function filepathMinusPrefix(filepath) {
+    const sourcePaths = getSourcePaths();
+    const commonPrefix = path.commonPrefix(sourcePaths);
+    let result = '';
+
+    if (filepath) {
+        filepath = path.normalize(filepath);
+        // always use forward slashes in the result
+        result = (filepath + path.sep).replace(commonPrefix, '')
+            .replace(/\\/g, '/');
+    }
+
+    if (result.length > 0 && result[result.length - 1] !== '/') {
+        result += '/';
+    }
+
+    return result;
+}
+
+/** @private */
+function setDocletKindToTitle(doclet, {title}) {
+    doclet.addTag( 'kind', title );
+}
+
+function setDocletScopeToTitle(doclet, {title}) {
+    try {
+        doclet.setScope(title);
+    }
+    catch (e) {
+        jsdoc.util.logger.error(e.message);
+    }
+}
+
+function setDocletNameToValue(doclet, {value, text}) {
+    if (value && value.description) { // as in a long tag
+        doclet.addTag('name', value.description);
+    }
+    else if (text) { // or a short tag
+        doclet.addTag('name', text);
+    }
+}
+
+function setDocletNameToValueName(doclet, {value}) {
+    if (value && value.name) {
+        doclet.addTag('name', value.name);
+    }
+}
+
+function setDocletDescriptionToValue(doclet, {value}) {
+    if (value) {
+        doclet.addTag('description', value);
+    }
+}
+
+function setDocletTypeToValueType(doclet, {value}) {
+    if (value && value.type) {
+        // Add the type names and other type properties (such as `optional`).
+        // Don't overwrite existing properties.
+        Object.keys(value).forEach(prop => {
+            if ( !hasOwnProp.call(doclet, prop) ) {
+                doclet[prop] = value[prop];
+            }
+        });
+    }
+}
+
+function setNameToFile(doclet) {
+    let name;
+
+    if (doclet.meta.filename) {
+        name = filepathMinusPrefix(doclet.meta.path) + doclet.meta.filename;
+        doclet.addTag('name', name);
+    }
+}
+
+function setDocletMemberof(doclet, {value}) {
+    if (value && value !== '<global>') {
+        doclet.setMemberof(value);
+    }
+}
+
+function applyNamespace(docletOrNs, tag) {
+    if (typeof docletOrNs === 'string') { // ns
+        tag.value = jsdoc.name.applyNamespace(tag.value, docletOrNs);
+    }
+    else { // doclet
+        if (!docletOrNs.name) {
+            return; // error?
+        }
+
+        docletOrNs.longname = jsdoc.name.applyNamespace(docletOrNs.name, tag.title);
+    }
+}
+
+function setDocletNameToFilename(doclet) {
+    let name = '';
+
+    if (doclet.meta.path) {
+        name = filepathMinusPrefix(doclet.meta.path);
+    }
+    name += doclet.meta.filename.replace(/\.js$/i, '');
+
+    doclet.name = name;
+}
+
+function parseTypeText(text) {
+    const tagType = jsdoc.tag.type.parse(text, false, true);
+
+    return tagType.typeExpression || text;
+}
+
+function parseBorrows(doclet, {text}) {
+    const m = /^([\s\S]+?)(?:\s+as\s+([\s\S]+))?$/.exec(text);
+
+    if (m) {
+        if (m[1] && m[2]) {
+            return {
+                target: m[1],
+                source: m[2]
+            };
+        }
+        else if (m[1]) {
+            return {
+                target: m[1]
+            };
+        }
+
+        return {};
+    } else {
+        return {};
+    }
+}
+
+function stripModuleNamespace(name) {
+    return name.replace(/^module:/, '');
+}
+
+function firstWordOf(string) {
+    const m = /^(\S+)/.exec(string);
+
+    if (m) {
+        return m[1];
+    }
+    else {
+        return '';
+    }
+}
+
+function combineTypes({value}) {
+    let combined;
+
+    if (value && value.type) {
+        if (value.type.names.length === 1) {
+            combined = value.type.names[0];
+        }
+        else {
+            combined = `(${value.type.names.join('|')})`;
+        }
+    }
+
+    return combined;
+}
+
+// Tags that JSDoc uses internally, and that must always be defined.
+const internalTags = {
+    // Special separator tag indicating that multiple doclets should be generated for the same
+    // comment. Used internally (and by some JSDoc users, although it's not officially supported).
+    // In the following example, the parser will replace `//**` with an `@also` tag:
+    // /**
+    //  * Foo.
+    //  *//**
+    //  * Foo with a param.
+    //  * @param {string} bar
+    //  */
+    //  function foo(bar) {}
+    also: {
+        onTagged() {
+            // let the parser handle it; we define the tag here to avoid "not a known tag" errors
+        }
+    },
+    description: {
+        mustHaveValue: true,
+        synonyms: ['desc']
+    },
+    kind: {
+        mustHaveValue: true
+    },
+    name: {
+        mustHaveValue: true
+    },
+    undocumented: {
+        mustNotHaveValue: true,
+        onTagged(doclet) {
+            doclet.undocumented = true;
+            doclet.comment = '';
+        }
+    }
+};
+
+// Core JSDoc tags that are shared with other tag dictionaries.
+let baseTags = exports.baseTags = {
+    abstract: {
+        mustNotHaveValue: true,
+        onTagged(doclet) {
+            // we call this `virtual` because `abstract` is a reserved word
+            doclet.virtual = true;
+        },
+        synonyms: ['virtual']
+    },
+    access: {
+        mustHaveValue: true,
+        onTagged(doclet, {value}) {
+            // only valid values are package, private, protected and public
+            if ( /^(package|private|protected|public)$/i.test(value) ) {
+                doclet.access = value.toLowerCase();
+            }
+            else {
+                delete doclet.access;
+            }
+        }
+    },
+    alias: {
+        mustHaveValue: true,
+        onTagged(doclet, {value}) {
+            doclet.alias = value;
+        }
+    },
+    async: {
+        mustNotHaveValue: true,
+        onTagged(doclet) {
+            doclet.async = true;
+        }
+    },
+    augments: {
+        mustHaveValue: true,
+        // Allow augments value to be specified as a normal type, e.g. {Type}
+        onTagText: parseTypeText,
+        onTagged(doclet, {value}) {
+            doclet.augment( firstWordOf(value) );
+        },
+        synonyms: ['extends']
+    },
+    author: {
+        mustHaveValue: true,
+        onTagged(doclet, {value}) {
+            doclet.author = doclet.author || [];
+            doclet.author.push(value);
+        }
+    },
+    // this symbol has a member that should use the same docs as another symbol
+    borrows: {
+        mustHaveValue: true,
+        onTagged(doclet, tag) {
+            const borrows = parseBorrows(doclet, tag);
+
+            doclet.borrow(borrows.target, borrows.source);
+        }
+    },
+    class: {
+        onTagged(doclet, tag) {
+            let looksLikeDesc;
+
+            doclet.addTag('kind', 'class');
+
+            // handle special case where both @class and @constructor tags exist in same doclet
+            if (tag.originalTitle === 'class') {
+                // multiple words after @class?
+                looksLikeDesc = (tag.value || '').match(/\S+\s+\S+/);
+                if ((looksLikeDesc || /@construct(s|or)\b/i.test(doclet.comment)) &&
+                    !/@classdesc\b/i.test(doclet.comment)) {
+                    // treat the @class tag as a @classdesc tag instead
+                    doclet.classdesc = tag.value;
+
+                    return;
+                }
+            }
+
+            setDocletNameToValue(doclet, tag);
+        },
+        synonyms: ['constructor']
+    },
+    classdesc: {
+        onTagged(doclet, {value}) {
+            doclet.classdesc = value;
+        }
+    },
+    constant: {
+        canHaveType: true,
+        canHaveName: true,
+        onTagged(doclet, tag) {
+            setDocletKindToTitle(doclet, tag);
+            setDocletNameToValueName(doclet, tag);
+            setDocletTypeToValueType(doclet, tag);
+        },
+        synonyms: ['const']
+    },
+    constructs: {
+        onTagged(doclet, {value}) {
+            let ownerClassName;
+
+            if (!value) {
+                // this can be resolved later in the handlers
+                ownerClassName = '{@thisClass}';
+            }
+            else {
+                ownerClassName = firstWordOf(value);
+            }
+            doclet.addTag('alias', ownerClassName);
+            doclet.addTag('kind', 'class');
+        }
+    },
+    copyright: {
+        mustHaveValue: true,
+        onTagged(doclet, {value}) {
+            doclet.copyright = value;
+        }
+    },
+    default: {
+        onTagged(doclet, {value}) {
+            const nodeToValue = jsdoc.src.astnode.nodeToValue;
+
+            if (value) {
+                doclet.defaultvalue = value;
+            }
+            else if (doclet.meta && doclet.meta.code &&
+                typeof doclet.meta.code.value !== 'undefined') {
+                switch (doclet.meta.code.type) {
+                    case Syntax.ArrayExpression:
+                        doclet.defaultvalue = nodeToValue(doclet.meta.code.node);
+                        doclet.defaultvaluetype = 'array';
+                        break;
+
+                    case Syntax.Literal:
+                        doclet.defaultvalue = doclet.meta.code.value;
+                        break;
+
+                    case Syntax.ObjectExpression:
+                        doclet.defaultvalue = nodeToValue(doclet.meta.code.node);
+                        doclet.defaultvaluetype = 'object';
+                        break;
+
+                    default:
+                        // do nothing
+                        break;
+                }
+            }
+        },
+        synonyms: ['defaultvalue']
+    },
+    deprecated: {
+        // value is optional
+        onTagged(doclet, {value}) {
+            doclet.deprecated = value || true;
+        }
+    },
+    enum: {
+        canHaveType: true,
+        onTagged(doclet, tag) {
+            doclet.kind = doclet.kind || 'member';
+            doclet.isEnum = true;
+            setDocletTypeToValueType(doclet, tag);
+        }
+    },
+    event: {
+        isNamespace: true,
+        onTagged(doclet, tag) {
+            setDocletKindToTitle(doclet, tag);
+            setDocletNameToValue(doclet, tag);
+        }
+    },
+    example: {
+        keepsWhitespace: true,
+        removesIndent: true,
+        mustHaveValue: true,
+        onTagged(doclet, {value}) {
+            doclet.examples = doclet.examples || [];
+            doclet.examples.push(value);
+        }
+    },
+    exports: {
+        mustHaveValue: true,
+        onTagged(doclet, {value}) {
+            const modName = firstWordOf(value);
+
+            // in case the user wrote something like `/** @exports module:foo */`:
+            doclet.addTag( 'alias', stripModuleNamespace(modName) );
+            doclet.addTag('kind', 'module');
+        }
+    },
+    external: {
+        canHaveType: true,
+        isNamespace: true,
+        onTagged(doclet, tag) {
+            setDocletKindToTitle(doclet, tag);
+            if (tag.value && tag.value.type) {
+                setDocletTypeToValueType(doclet, tag);
+                doclet.addTag('name', doclet.type.names[0]);
+            }
+            else {
+                setDocletNameToValue(doclet, tag);
+            }
+        },
+        synonyms: ['host']
+    },
+    file: {
+        onTagged(doclet, tag) {
+            setNameToFile(doclet);
+            setDocletKindToTitle(doclet, tag);
+            setDocletDescriptionToValue(doclet, tag);
+
+            doclet.preserveName = true;
+        },
+        synonyms: ['fileoverview', 'overview']
+    },
+    fires: {
+        mustHaveValue: true,
+        onTagged(doclet, tag) {
+            doclet.fires = doclet.fires || [];
+            applyNamespace('event', tag);
+            doclet.fires.push(tag.value);
+        },
+        synonyms: ['emits']
+    },
+    function: {
+        onTagged(doclet, tag) {
+            setDocletKindToTitle(doclet, tag);
+            setDocletNameToValue(doclet, tag);
+        },
+        synonyms: ['func', 'method']
+    },
+    generator: {
+        mustNotHaveValue: true,
+        onTagged(doclet) {
+            doclet.generator = true;
+        }
+    },
+    global: {
+        mustNotHaveValue: true,
+        onTagged(doclet) {
+            doclet.scope = jsdoc.name.SCOPE.NAMES.GLOBAL;
+            delete doclet.memberof;
+        }
+    },
+    hideconstructor: {
+        mustNotHaveValue: true,
+        onTagged(doclet) {
+            doclet.hideconstructor = true;
+        }
+    },
+    ignore: {
+        mustNotHaveValue: true,
+        onTagged(doclet) {
+            doclet.ignore = true;
+        }
+    },
+    implements: {
+        mustHaveValue: true,
+        onTagText: parseTypeText,
+        onTagged(doclet, {value}) {
+            doclet.implements = doclet.implements || [];
+            doclet.implements.push(value);
+        }
+    },
+    inheritdoc: {
+        mustNotHaveValue: true,
+        onTagged(doclet) {
+            // use an empty string so JSDoc can support `@inheritdoc Foo#bar` in the future
+            doclet.inheritdoc = '';
+        }
+    },
+    inner: {
+        onTagged(doclet, tag) {
+            setDocletScopeToTitle(doclet, tag);
+        }
+    },
+    instance: {
+        onTagged(doclet, tag) {
+            setDocletScopeToTitle(doclet, tag);
+        }
+    },
+    interface: {
+        canHaveName: true,
+        onTagged(doclet, tag) {
+            doclet.addTag('kind', 'interface');
+            if (tag.value) {
+                setDocletNameToValueName(doclet, tag);
+            }
+        }
+    },
+    lends: {
+        onTagged(doclet, {value}) {
+            doclet.alias = value || jsdoc.name.LONGNAMES.GLOBAL;
+            doclet.addTag('undocumented');
+        }
+    },
+    license: {
+        mustHaveValue: true,
+        onTagged(doclet, {value}) {
+            doclet.license = value;
+        }
+    },
+    listens: {
+        mustHaveValue: true,
+        onTagged(doclet, tag) {
+            doclet.listens = doclet.listens || [];
+            applyNamespace('event', tag);
+            doclet.listens.push(tag.value);
+        }
+    },
+    member: {
+        canHaveType: true,
+        canHaveName: true,
+        onTagged(doclet, tag) {
+            setDocletKindToTitle(doclet, tag);
+            setDocletNameToValueName(doclet, tag);
+            setDocletTypeToValueType(doclet, tag);
+        },
+        synonyms: ['var']
+    },
+    memberof: {
+        mustHaveValue: true,
+        onTagged(doclet, tag) {
+            if (tag.originalTitle === 'memberof!') {
+                doclet.forceMemberof = true;
+                if (tag.value === jsdoc.name.LONGNAMES.GLOBAL) {
+                    doclet.addTag('global');
+                    delete doclet.memberof;
+                }
+            }
+            setDocletMemberof(doclet, tag);
+        },
+        synonyms: ['memberof!']
+    },
+    // this symbol mixes in all of the specified object's members
+    mixes: {
+        mustHaveValue: true,
+        onTagged(doclet, {value}) {
+            const source = firstWordOf(value);
+
+            doclet.mix(source);
+        }
+    },
+    mixin: {
+        onTagged(doclet, tag) {
+            setDocletKindToTitle(doclet, tag);
+            setDocletNameToValue(doclet, tag);
+        }
+    },
+    modifies: {
+        canHaveType: true,
+        onTagged(doclet, {value}) {
+            doclet.modifies = doclet.modifies || [];
+            doclet.modifies.push(value);
+        }
+    },
+    module: {
+        canHaveType: true,
+        isNamespace: true,
+        onTagged(doclet, tag) {
+            setDocletKindToTitle(doclet, tag);
+            setDocletNameToValue(doclet, tag);
+            if (!doclet.name) {
+                setDocletNameToFilename(doclet);
+            }
+            // in case the user wrote something like `/** @module module:foo */`:
+            doclet.name = stripModuleNamespace(doclet.name);
+
+            setDocletTypeToValueType(doclet, tag);
+        }
+    },
+    namespace: {
+        canHaveType: true,
+        onTagged(doclet, tag) {
+            setDocletKindToTitle(doclet, tag);
+            setDocletNameToValue(doclet, tag);
+            setDocletTypeToValueType(doclet, tag);
+        }
+    },
+    package: {
+        mustNotHaveValue: true,
+        onTagged(doclet) {
+            doclet.access = 'package';
+        }
+    },
+    param: {
+        canHaveType: true,
+        canHaveName: true,
+        onTagged(doclet, {value}) {
+            doclet.params = doclet.params || [];
+            doclet.params.push(value || {});
+        },
+        synonyms: ['arg', 'argument']
+    },
+    private: {
+        mustNotHaveValue: true,
+        onTagged(doclet) {
+            doclet.access = 'private';
+        }
+    },
+    property: {
+        mustHaveValue: true,
+        canHaveType: true,
+        canHaveName: true,
+        onTagged(doclet, {value}) {
+            doclet.properties = doclet.properties || [];
+            doclet.properties.push(value);
+        },
+        synonyms: ['prop']
+    },
+    protected: {
+        mustNotHaveValue: true,
+        onTagged(doclet) {
+            doclet.access = 'protected';
+        }
+    },
+    public: {
+        mustNotHaveValue: true,
+        onTagged(doclet) {
+            doclet.access = 'public';
+        }
+    },
+    readonly: {
+        mustNotHaveValue: true,
+        onTagged(doclet) {
+            doclet.readonly = true;
+        }
+    },
+    requires: {
+        mustHaveValue: true,
+        onTagged(doclet, {value}) {
+            let requiresName;
+
+            // inline link tags are passed through as-is so that `@requires {@link foo}` works
+            if ( jsdoc.tag.inline.isInlineTag(value, 'link\\S*') ) {
+                requiresName = value;
+            }
+            // otherwise, assume it's a module
+            else {
+                requiresName = firstWordOf(value);
+                if (requiresName.indexOf(MODULE_NAMESPACE) !== 0) {
+                    requiresName = MODULE_NAMESPACE + requiresName;
+                }
+            }
+
+            doclet.requires = doclet.requires || [];
+            doclet.requires.push(requiresName);
+        }
+    },
+    returns: {
+        mustHaveValue: true,
+        canHaveType: true,
+        onTagged(doclet, {value}) {
+            doclet.returns = doclet.returns || [];
+            doclet.returns.push(value);
+        },
+        synonyms: ['return']
+    },
+    see: {
+        mustHaveValue: true,
+        onTagged(doclet, {value}) {
+            doclet.see = doclet.see || [];
+            doclet.see.push(value);
+        }
+    },
+    since: {
+        mustHaveValue: true,
+        onTagged(doclet, {value}) {
+            doclet.since = value;
+        }
+    },
+    static: {
+        onTagged(doclet, tag) {
+            setDocletScopeToTitle(doclet, tag);
+        }
+    },
+    summary: {
+        mustHaveValue: true,
+        onTagged(doclet, {value}) {
+            doclet.summary = value;
+        }
+    },
+    'this': {
+        mustHaveValue: true,
+        onTagged(doclet, {value}) {
+            doclet.this = firstWordOf(value);
+        }
+    },
+    todo: {
+        mustHaveValue: true,
+        onTagged(doclet, {value}) {
+            doclet.todo = doclet.todo || [];
+            doclet.todo.push(value);
+        }
+    },
+    throws: {
+        mustHaveValue: true,
+        canHaveType: true,
+        onTagged(doclet, {value}) {
+            doclet.exceptions = doclet.exceptions || [];
+            doclet.exceptions.push(value);
+        },
+        synonyms: ['exception']
+    },
+    tutorial: {
+        mustHaveValue: true,
+        onTagged(doclet, {value}) {
+            doclet.tutorials = doclet.tutorials || [];
+            doclet.tutorials.push(value);
+        }
+    },
+    type: {
+        mustHaveValue: true,
+        mustNotHaveDescription: true,
+        canHaveType: true,
+        onTagText(text) {
+            let closeIdx;
+            let openIdx;
+
+            const OPEN_BRACE = '{';
+            const CLOSE_BRACE = '}';
+
+            // remove line breaks
+            text = text.replace(/[\f\n\r]/g, '');
+
+            // Text must be a type expression; for backwards compatibility, we add braces if they're
+            // missing. But do NOT add braces to things like `@type {string} some pointless text`.
+            openIdx = text.indexOf(OPEN_BRACE);
+            closeIdx = text.indexOf(CLOSE_BRACE);
+
+            // a type expression is at least one character long
+            if ( openIdx !== 0 || closeIdx <= openIdx + 1) {
+                text = OPEN_BRACE + text + CLOSE_BRACE;
+            }
+
+            return text;
+        },
+        onTagged(doclet, tag) {
+            if (tag.value && tag.value.type) {
+                setDocletTypeToValueType(doclet, tag);
+
+                // for backwards compatibility, we allow @type for functions to imply return type
+                if (doclet.kind === 'function') {
+                    doclet.addTag('returns', tag.text);
+                }
+            }
+        }
+    },
+    typedef: {
+        canHaveType: true,
+        canHaveName: true,
+        onTagged(doclet, tag) {
+            setDocletKindToTitle(doclet, tag);
+
+            if (tag.value) {
+                setDocletNameToValueName(doclet, tag);
+
+                // callbacks are always type {function}
+                if (tag.originalTitle === 'callback') {
+                    doclet.type = {
+                        names: [
+                            'function'
+                        ]
+                    };
+                }
+                else {
+                    setDocletTypeToValueType(doclet, tag);
+                }
+            }
+        },
+        synonyms: ['callback']
+    },
+    variation: {
+        mustHaveValue: true,
+        onTagged(doclet, tag) {
+            let value = tag.value;
+
+            if ( /^\((.+)\)$/.test(value) ) {
+                value = RegExp.$1;
+            }
+
+            doclet.variation = value;
+        }
+    },
+    version: {
+        mustHaveValue: true,
+        onTagged(doclet, {value}) {
+            doclet.version = value;
+        }
+    },
+    yields: {
+        mustHaveValue: true,
+        canHaveType: true,
+        onTagged(doclet, {value}) {
+            doclet.yields = doclet.yields || [];
+            doclet.yields.push(value);
+        },
+        synonyms: ['yield']
+    }
+};
+
+baseTags = _.extend(baseTags, internalTags);
+
+// Tag dictionary for JSDoc.
+exports.jsdocTags = baseTags;
+
+function ignore() {
+    // do nothing
+}
+
+// Tag dictionary for Google Closure Compiler.
+exports.closureTags = {
+    const: {
+        canHaveType: true,
+        onTagged(doclet, tag) {
+            doclet.kind = 'constant';
+            setDocletTypeToValueType(doclet, tag);
+        },
+        // Closure Compiler only
+        synonyms: ['define']
+    },
+    constructor: cloneTagDef(baseTags.class),
+    deprecated: cloneTagDef(baseTags.deprecated),
+    // Closure Compiler only
+    dict: {
+        onTagged: ignore
+    },
+    enum: cloneTagDef(baseTags.enum),
+    // Closure Compiler only
+    export: {
+        onTagged: ignore
+    },
+    // Closure Compiler only
+    externs: {
+        onTagged: ignore
+    },
+    extends: cloneTagDef(baseTags.augments),
+    fileoverview: {
+        onTagged(doclet, tag) {
+            setNameToFile(doclet);
+            doclet.kind = 'file';
+            setDocletDescriptionToValue(doclet, tag);
+
+            doclet.preserveName = true;
+        }
+    },
+    final: cloneTagDef(baseTags.readonly),
+    implements: cloneTagDef(baseTags.implements),
+    // Closure Compiler only
+    implicitcast: {
+        onTagged: ignore
+    },
+    inheritdoc: cloneTagDef(baseTags.inheritdoc),
+    interface: cloneTagDef(baseTags.interface, {
+        canHaveName: false,
+        mustNotHaveValue: true,
+        // Closure Compiler only
+        synonyms: ['record']
+    }),
+    lends: cloneTagDef(baseTags.lends),
+    license: cloneTagDef(baseTags.license),
+    modifies: cloneTagDef(baseTags.modifies),
+    // Closure Compiler only
+    noalias: {
+        onTagged: ignore
+    },
+    // Closure Compiler only
+    nocollapse: {
+        onTagged: ignore
+    },
+    // Closure Compiler only
+    nocompile: {
+        onTagged: ignore
+    },
+    // Closure Compiler only
+    nosideeffects: {
+        onTagged(doclet) {
+            doclet.modifies = [];
+        }
+    },
+    // Closure Compiler only
+    override: {
+        mustNotHaveValue: true,
+        onTagged(doclet) {
+            doclet.override = true;
+        }
+    },
+    package: {
+        canHaveType: true,
+        onTagged(doclet, tag) {
+            doclet.access = 'package';
+
+            if (tag.value && tag.value.type) {
+                setDocletTypeToValueType(doclet, tag);
+            }
+        }
+    },
+    param: cloneTagDef(baseTags.param),
+    // Closure Compiler only
+    polymer: {
+        onTagged: ignore
+    },
+    // Closure Compiler only
+    polymerBehavior: {
+        onTagged: ignore
+    },
+    // Closure Compiler only
+    preserve: cloneTagDef(baseTags.license),
+    private: {
+        canHaveType: true,
+        onTagged(doclet, tag) {
+            doclet.access = 'private';
+
+            if (tag.value && tag.value.type) {
+                setDocletTypeToValueType(doclet, tag);
+            }
+        }
+    },
+    protected: {
+        canHaveType: true,
+        onTagged(doclet, tag) {
+            doclet.access = 'protected';
+
+            if (tag.value && tag.value.type) {
+                setDocletTypeToValueType(doclet, tag);
+            }
+        }
+    },
+    public: {
+        canHaveType: true,
+        onTagged(doclet, tag) {
+            doclet.access = 'public';
+
+            if (tag.value && tag.value.type) {
+                setDocletTypeToValueType(doclet, tag);
+            }
+        }
+    },
+    return: cloneTagDef(baseTags.returns),
+    // Closure Compiler only
+    struct: {
+        onTagged: ignore
+    },
+    // Closure Compiler only
+    suppress: {
+        onTagged: ignore
+    },
+    // Closure Compiler only
+    template: {
+        onTagged: ignore
+    },
+    'this': {
+        canHaveType: true,
+        onTagged(doclet, tag) {
+            doclet.this = combineTypes(tag);
+        }
+    },
+    throws: cloneTagDef(baseTags.throws),
+    type: cloneTagDef(baseTags.type, {
+        mustNotHaveDescription: false
+    }),
+    typedef: {
+        canHaveType: true,
+        onTagged(doclet, tag) {
+            setDocletKindToTitle(doclet, tag);
+            setDocletTypeToValueType(doclet, tag);
+        }
+    },
+    // Closure Compiler only
+    unrestricted: {
+        onTagged: ignore
+    }
+};
+
+function addTagDefinitions(dictionary, tagDefs) {
+    Object.keys(tagDefs).forEach(tagName => {
+        let tagDef;
+
+        tagDef = tagDefs[tagName];
+        dictionary.defineTag(tagName, tagDef);
+
+        if (tagDef.synonyms) {
+            tagDef.synonyms.forEach(synonym => {
+                dictionary.defineSynonym(tagName, synonym);
+            });
+        }
+    });
+}
+
+/**
+ * Populate the given dictionary with the appropriate JSDoc tag definitions.
+ *
+ * If the `tagDefinitions` parameter is omitted, JSDoc uses its configuration settings to decide
+ * which tags to add to the dictionary.
+ *
+ * If the `tagDefinitions` parameter is included, JSDoc adds only the tag definitions from the
+ * `tagDefinitions` object. The configuration settings are ignored.
+ *
+ * @param {module:jsdoc/tag/dictionary} dictionary
+ * @param {Object} [tagDefinitions] - A dictionary whose values define the rules for a JSDoc tag.
+ */
+exports.defineTags = (dictionary, tagDefinitions) => {
+    let dictionaries;
+
+    if (!tagDefinitions) {
+        dictionaries = jsdoc.env.conf.tags.dictionaries;
+
+        if (!dictionaries) {
+            jsdoc.util.logger.error('The configuration setting "tags.dictionaries" is undefined. ' +
+                'Unable to load tag definitions.');
+
+            return;
+        }
+        else {
+            dictionaries = dictionaries.slice(0).reverse();
+        }
+
+        dictionaries.forEach(dictName => {
+            const tagDefs = exports[DEFINITIONS[dictName]];
+
+            if (!tagDefs) {
+                jsdoc.util.logger.error('The configuration setting "tags.dictionaries" contains ' +
+                    'the unknown dictionary name %s. Ignoring the dictionary.', dictName);
+
+                return;
+            }
+
+            addTagDefinitions(dictionary, _.extend(tagDefs, internalTags));
+        });
+    }
+    else {
+        addTagDefinitions(dictionary, _.extend(tagDefinitions, internalTags));
+    }
+};