Source: tag/dictionary/definitions.js

  1. /**
  2.     Define tags that are known in JSDoc.
  3.     @module jsdoc/tag/dictionary/definitions
  5.     @author Michael Mathews <micmath@gmail.com>
  6.     @license Apache License 2.0 - See file 'LICENSE.md' in this project.
  7.  */
  8. 'use strict';
  10. var _ = require('underscore');
  11. var jsdoc = {
  12.     env: require('jsdoc/env'),
  13.     name: require('jsdoc/name'),
  14.     src: {
  15.         astnode: require('jsdoc/src/astnode')
  16.     },
  17.     tag: {
  18.         type: require('jsdoc/tag/type')
  19.     },
  20.     util: {
  21.         doop: require('jsdoc/util/doop'),
  22.         logger: require('jsdoc/util/logger')
  23.     }
  24. };
  25. var path = require('jsdoc/path');
  26. var Syntax = require('jsdoc/src/syntax').Syntax;
  28. var hasOwnProp = Object.prototype.hasOwnProperty;
  30. var DEFINITIONS = {
  31.     closure: 'closureTags',
  32.     jsdoc: 'jsdocTags'
  33. };
  34. var MODULE_NAMESPACE = 'module:';
  36. // Clone a tag definition, excluding synonyms.
  37. function cloneTagDef(tagDef, extras) {
  38.     var newTagDef = jsdoc.util.doop(tagDef);
  39.     delete newTagDef.synonyms;
  41.     return (extras ? _.extend(newTagDef, extras) : newTagDef);
  42. }
  44. function getSourcePaths() {
  45.     var sourcePaths = jsdoc.env.sourceFiles.slice(0) || [];
  47.     if (jsdoc.env.opts._) {
  48.         jsdoc.env.opts._.forEach(function(sourcePath) {
  49.             var resolved = path.resolve(jsdoc.env.pwd, sourcePath);
  50.             if (sourcePaths.indexOf(resolved) === -1) {
  51.                 sourcePaths.push(resolved);
  52.             }
  53.         });
  54.     }
  56.     return sourcePaths;
  57. }
  59. function filepathMinusPrefix(filepath) {
  60.     var sourcePaths = getSourcePaths();
  61.     var commonPrefix = path.commonPrefix(sourcePaths);
  62.     var result = '';
  64.     if (filepath) {
  65.         filepath = path.normalize(filepath);
  66.         // always use forward slashes in the result
  67.         result = (filepath + path.sep).replace(commonPrefix, '')
  68.             .replace(/\\/g, '/');
  69.     }
  71.     if (result.length > 0 && result[result.length - 1] !== '/') {
  72.         result += '/';
  73.     }
  75.     return result;
  76. }
  78. /** @private */
  79. function setDocletKindToTitle(doclet, tag) {
  80.     doclet.addTag( 'kind', tag.title );
  81. }
  83. function setDocletScopeToTitle(doclet, tag) {
  84.     try {
  85.         doclet.setScope(tag.title);
  86.     }
  87.     catch(e) {
  88.         jsdoc.util.logger.error(e.message);
  89.     }
  90. }
  92. function setDocletNameToValue(doclet, tag) {
  93.     if (tag.value && tag.value.description) { // as in a long tag
  94.         doclet.addTag('name', tag.value.description);
  95.     }
  96.     else if (tag.text) { // or a short tag
  97.         doclet.addTag('name', tag.text);
  98.     }
  99. }
  101. function setDocletNameToValueName(doclet, tag) {
  102.     if (tag.value && tag.value.name) {
  103.         doclet.addTag('name', tag.value.name);
  104.     }
  105. }
  107. function setDocletDescriptionToValue(doclet, tag) {
  108.     if (tag.value) {
  109.         doclet.addTag('description', tag.value);
  110.     }
  111. }
  113. function setDocletTypeToValueType(doclet, tag) {
  114.     if (tag.value && tag.value.type) {
  115.         // Add the type names and other type properties (such as `optional`).
  116.         // Don't overwrite existing properties.
  117.         Object.keys(tag.value).forEach(function(prop) {
  118.             if ( !hasOwnProp.call(doclet, prop) ) {
  119.                 doclet[prop] = tag.value[prop];
  120.             }
  121.         });
  122.     }
  123. }
  125. function setNameToFile(doclet, tag) {
  126.     var name;
  128.     if (doclet.meta.filename) {
  129.         name = filepathMinusPrefix(doclet.meta.path) + doclet.meta.filename;
  130.         doclet.addTag('name', name);
  131.     }
  132. }
  134. function setDocletMemberof(doclet, tag) {
  135.     if (tag.value && tag.value !== '<global>') {
  136.         doclet.setMemberof(tag.value);
  137.     }
  138. }
  140. function applyNamespace(docletOrNs, tag) {
  141.     if (typeof docletOrNs === 'string') { // ns
  142.         tag.value = jsdoc.name.applyNamespace(tag.value, docletOrNs);
  143.     }
  144.     else { // doclet
  145.         if (!docletOrNs.name) {
  146.             return; // error?
  147.         }
  149.         docletOrNs.longname = jsdoc.name.applyNamespace(docletOrNs.name, tag.title);
  150.     }
  151. }
  153. function setDocletNameToFilename(doclet, tag) {
  154.     var name = '';
  156.     if (doclet.meta.path) {
  157.         name = filepathMinusPrefix(doclet.meta.path);
  158.     }
  159.     name += doclet.meta.filename.replace(/\.js$/i, '');
  161.     doclet.name = name;
  162. }
  164. function parseTypeText(text) {
  165.     var tagType = jsdoc.tag.type.parse(text, false, true);
  166.     return tagType.typeExpression || text;
  167. }
  169. function parseBorrows(doclet, tag) {
  170.     var m = /^([\s\S]+?)(?:\s+as\s+([\s\S]+))?$/.exec(tag.text);
  171.     if (m) {
  172.         if (m[1] && m[2]) {
  173.             return { target: m[1], source: m[2] };
  174.         }
  175.         else if (m[1]) {
  176.             return { target: m[1] };
  177.         }
  178.     } else {
  179.         return {};
  180.     }
  181. }
  183. function stripModuleNamespace(name) {
  184.     return name.replace(/^module\:/, '');
  185. }
  187. function firstWordOf(string) {
  188.     var m = /^(\S+)/.exec(string);
  189.     if (m) { return m[1]; }
  190.     else { return ''; }
  191. }
  194. // Core JSDoc tags that are shared with other tag dictionaries.
  195. var baseTags = exports.baseTags = {
  196.     abstract: {
  197.         mustNotHaveValue: true,
  198.         onTagged: function(doclet, tag) {
  199.             // we call this `virtual` because `abstract` is a reserved word
  200.             doclet.virtual = true;
  201.         },
  202.         synonyms: ['virtual']
  203.     },
  204.     access: {
  205.         mustHaveValue: true,
  206.         onTagged: function(doclet, tag) {
  207.             // only valid values are private, protected and public
  208.             if ( /^(private|protected|public)$/i.test(tag.value) ) {
  209.                 doclet.access = tag.value.toLowerCase();
  210.             }
  211.             else {
  212.                 delete doclet.access;
  213.             }
  214.         }
  215.     },
  216.     alias: {
  217.         mustHaveValue: true,
  218.         onTagged: function(doclet, tag) {
  219.             doclet.alias = tag.value;
  220.         }
  221.     },
  222.     // Special separator tag indicating that multiple doclets should be generated for the same
  223.     // comment. Used internally (and by some JSDoc users, although it's not officially supported).
  224.     // In the following example, the parser will replace `//**` with an `@also` tag:
  225.     // /**
  226.     //  * Foo.
  227.     //  *//**
  228.     //  * Foo with a param.
  229.     //  * @param {string} bar
  230.     //  */
  231.     //  function foo(bar) {}
  232.     also: {
  233.         onTagged: function(doclet, tag) {
  234.             // let the parser handle it; we define the tag here to avoid "not a known tag" errors
  235.         }
  236.     },
  237.     augments: {
  238.         mustHaveValue: true,
  239.         // Allow augments value to be specified as a normal type, e.g. {Type}
  240.         onTagText: parseTypeText,
  241.         onTagged: function(doclet, tag) {
  242.             doclet.augment( firstWordOf(tag.value) );
  243.         },
  244.         synonyms: ['extends']
  245.     },
  246.     author: {
  247.         mustHaveValue: true,
  248.         onTagged: function(doclet, tag) {
  249.             doclet.author = doclet.author || [];
  250.             doclet.author.push(tag.value);
  251.         }
  252.     },
  253.     // this symbol has a member that should use the same docs as another symbol
  254.     borrows: {
  255.         mustHaveValue: true,
  256.         onTagged: function(doclet, tag) {
  257.             var borrows = parseBorrows(doclet, tag);
  258.             doclet.borrow(borrows.target, borrows.source);
  259.         }
  260.     },
  261.     class: {
  262.         onTagged: function(doclet, tag) {
  263.             doclet.addTag('kind', 'class');
  265.             // handle special case where both @class and @constructor tags exist in same doclet
  266.             if (tag.originalTitle === 'class') {
  267.                 // multiple words after @class?
  268.                 var looksLikeDesc = (tag.value || '').match(/\S+\s+\S+/);
  269.                 if ((looksLikeDesc || /@construct(s|or)\b/i.test(doclet.comment)) &&
  270.                     !/@classdesc\b/i.test(doclet.comment)) {
  271.                     // treat the @class tag as a @classdesc tag instead
  272.                     doclet.classdesc = tag.value;
  273.                     return;
  274.                 }
  275.             }
  277.             setDocletNameToValue(doclet, tag);
  278.         },
  279.         synonyms: ['constructor']
  280.     },
  281.     classdesc: {
  282.         onTagged: function(doclet, tag) {
  283.             doclet.classdesc = tag.value;
  284.         }
  285.     },
  286.     constant: {
  287.         canHaveType: true,
  288.         canHaveName: true,
  289.         onTagged: function(doclet, tag) {
  290.             setDocletKindToTitle(doclet, tag);
  291.             setDocletNameToValueName(doclet, tag);
  292.             setDocletTypeToValueType(doclet, tag);
  293.         },
  294.         synonyms: ['const']
  295.     },
  296.     constructs: {
  297.         onTagged: function(doclet, tag) {
  298.             var ownerClassName;
  299.             if (!tag.value) {
  300.                 // this can be resolved later in the handlers
  301.                 ownerClassName = '{@thisClass}';
  302.             }
  303.             else {
  304.                 ownerClassName = firstWordOf(tag.value);
  305.             }
  306.             doclet.addTag('alias', ownerClassName);
  307.             doclet.addTag('kind', 'class');
  308.         }
  309.     },
  310.     copyright: {
  311.         mustHaveValue: true,
  312.         onTagged: function(doclet, tag) {
  313.             doclet.copyright = tag.value;
  314.         }
  315.     },
  316.     default: {
  317.         onTagged: function(doclet, tag) {
  318.             var nodeToValue = jsdoc.src.astnode.nodeToValue;
  320.             if (tag.value) {
  321.                 doclet.defaultvalue = tag.value;
  322.             }
  323.             else if (doclet.meta && doclet.meta.code &&
  324.                 typeof doclet.meta.code.value !== 'undefined') {
  325.                 switch (doclet.meta.code.type) {
  326.                     case Syntax.ArrayExpression:
  327.                         doclet.defaultvalue = nodeToValue(doclet.meta.code.node);
  328.                         doclet.defaultvaluetype = 'array';
  329.                         break;
  331.                     case Syntax.Literal:
  332.                         doclet.defaultvalue = doclet.meta.code.value;
  333.                         break;
  335.                     case Syntax.ObjectExpression:
  336.                         doclet.defaultvalue = nodeToValue(doclet.meta.code.node);
  337.                         doclet.defaultvaluetype = 'object';
  338.                         break;
  340.                     default:
  341.                         // do nothing
  342.                         break;
  343.                 }
  344.             }
  345.         },
  346.         synonyms: ['defaultvalue']
  347.     },
  348.     deprecated: {
  349.         // value is optional
  350.         onTagged: function(doclet, tag) {
  351.             doclet.deprecated = tag.value || true;
  352.         }
  353.     },
  354.     description: {
  355.         mustHaveValue: true,
  356.         synonyms: ['desc']
  357.     },
  358.     enum: {
  359.         canHaveType: true,
  360.         onTagged: function(doclet, tag) {
  361.             doclet.kind = 'member';
  362.             doclet.isEnum = true;
  363.             setDocletTypeToValueType(doclet, tag);
  364.         }
  365.     },
  366.     event: {
  367.         isNamespace: true,
  368.         onTagged: function(doclet, tag) {
  369.             setDocletKindToTitle(doclet, tag);
  370.             setDocletNameToValue(doclet, tag);
  371.         }
  372.     },
  373.     example: {
  374.         keepsWhitespace: true,
  375.         removesIndent: true,
  376.         mustHaveValue: true,
  377.         onTagged: function(doclet, tag) {
  378.             doclet.examples = doclet.examples || [];
  379.             doclet.examples.push(tag.value);
  380.         }
  381.     },
  382.     exports: {
  383.         mustHaveValue: true,
  384.         onTagged: function(doclet, tag) {
  385.             var modName = firstWordOf(tag.value);
  387.             // in case the user wrote something like `/** @exports module:foo */`:
  388.             doclet.addTag( 'alias', stripModuleNamespace(modName) );
  389.             doclet.addTag('kind', 'module');
  390.          }
  391.     },
  392.     external: {
  393.         canHaveType: true,
  394.         isNamespace: true,
  395.         onTagged: function(doclet, tag) {
  396.             setDocletKindToTitle(doclet, tag);
  397.             if (tag.value && tag.value.type) {
  398.                 setDocletTypeToValueType(doclet, tag);
  399.                 doclet.addTag('name', doclet.type.names[0]);
  400.             }
  401.             else {
  402.                 setDocletNameToValue(doclet, tag);
  403.             }
  404.         },
  405.         synonyms: ['host']
  406.     },
  407.     file: {
  408.         onTagged: function(doclet, tag) {
  409.             setNameToFile(doclet, tag);
  410.             setDocletKindToTitle(doclet, tag);
  411.             setDocletDescriptionToValue(doclet, tag);
  413.             doclet.preserveName = true;
  414.         },
  415.         synonyms: ['fileoverview', 'overview']
  416.     },
  417.     fires: {
  418.         mustHaveValue: true,
  419.         onTagged: function(doclet, tag) {
  420.             doclet.fires = doclet.fires || [];
  421.             applyNamespace('event', tag);
  422.             doclet.fires.push(tag.value);
  423.         },
  424.         synonyms: ['emits']
  425.     },
  426.     function: {
  427.         onTagged: function(doclet, tag) {
  428.             setDocletKindToTitle(doclet, tag);
  429.             setDocletNameToValue(doclet, tag);
  430.         },
  431.         synonyms: ['func', 'method']
  432.     },
  433.     global: {
  434.         mustNotHaveValue: true,
  435.         onTagged: function(doclet, tag) {
  436.             doclet.scope = jsdoc.name.SCOPE.NAMES.GLOBAL;
  437.             delete doclet.memberof;
  438.         }
  439.     },
  440.     ignore: {
  441.         mustNotHaveValue: true,
  442.         onTagged: function(doclet, tag) {
  443.             doclet.ignore = true;
  444.         }
  445.     },
  446.     implements: {
  447.         mustHaveValue: true,
  448.         onTagText: parseTypeText,
  449.         onTagged: function(doclet, tag) {
  450.             doclet.implements = doclet.implements || [];
  451.             doclet.implements.push(tag.value);
  452.         }
  453.     },
  454.     inheritdoc: {
  455.         mustNotHaveValue: true,
  456.         onTagged: function(doclet, tag) {
  457.             // use an empty string so JSDoc can support `@inheritdoc Foo#bar` in the future
  458.             doclet.inheritdoc = '';
  459.         }
  460.     },
  461.     inner: {
  462.         onTagged: function(doclet, tag) {
  463.             setDocletScopeToTitle(doclet, tag);
  464.         }
  465.     },
  466.     instance: {
  467.         onTagged: function(doclet, tag) {
  468.             setDocletScopeToTitle(doclet, tag);
  469.         }
  470.     },
  471.     interface: {
  472.         canHaveName: true,
  473.         onTagged: function(doclet, tag) {
  474.             doclet.addTag('kind', 'interface');
  475.             if (tag.value) {
  476.                 setDocletNameToValueName(doclet, tag);
  477.             }
  478.         }
  479.     },
  480.     kind: {
  481.         mustHaveValue: true
  482.     },
  483.     lends: {
  484.         onTagged: function(doclet, tag) {
  485.             doclet.alias = tag.value || jsdoc.name.LONGNAMES.GLOBAL;
  486.             doclet.addTag('undocumented');
  487.         }
  488.     },
  489.     license: {
  490.         mustHaveValue: true,
  491.         onTagged: function(doclet, tag) {
  492.             doclet.license = tag.value;
  493.         }
  494.     },
  495.     listens: {
  496.         mustHaveValue: true,
  497.         onTagged: function (doclet, tag) {
  498.             doclet.listens = doclet.listens || [];
  499.             applyNamespace('event', tag);
  500.             doclet.listens.push(tag.value);
  501.         }
  502.     },
  503.     member: {
  504.         canHaveType: true,
  505.         canHaveName: true,
  506.         onTagged: function(doclet, tag) {
  507.             setDocletKindToTitle(doclet, tag);
  508.             setDocletNameToValueName(doclet, tag);
  509.             setDocletTypeToValueType(doclet, tag);
  510.         },
  511.         synonyms: ['var']
  512.     },
  513.     memberof: {
  514.         mustHaveValue: true,
  515.         onTagged: function(doclet, tag) {
  516.             if (tag.originalTitle === 'memberof!') {
  517.                 doclet.forceMemberof = true;
  518.                 if (tag.value === jsdoc.name.LONGNAMES.GLOBAL) {
  519.                     doclet.addTag('global');
  520.                     delete doclet.memberof;
  521.                 }
  522.             }
  523.             setDocletMemberof(doclet, tag);
  524.          },
  525.          synonyms: ['memberof!']
  526.     },
  527.     // this symbol mixes in all of the specified object's members
  528.     mixes: {
  529.         mustHaveValue: true,
  530.         onTagged: function(doclet, tag) {
  531.             var source = firstWordOf(tag.value);
  532.             doclet.mix(source);
  533.         }
  534.     },
  535.     mixin: {
  536.         onTagged: function(doclet, tag) {
  537.             setDocletKindToTitle(doclet, tag);
  538.             setDocletNameToValue(doclet, tag);
  539.         }
  540.     },
  541.     module: {
  542.         canHaveType: true,
  543.         isNamespace: true,
  544.         onTagged: function(doclet, tag) {
  545.             setDocletKindToTitle(doclet, tag);
  546.             setDocletNameToValue(doclet, tag);
  547.             if (!doclet.name) {
  548.                 setDocletNameToFilename(doclet, tag);
  549.             }
  550.             // in case the user wrote something like `/** @module module:foo */`:
  551.             doclet.name = stripModuleNamespace(doclet.name);
  553.             setDocletTypeToValueType(doclet, tag);
  554.         }
  555.     },
  556.     name: {
  557.         mustHaveValue: true
  558.     },
  559.     namespace: {
  560.         canHaveType: true,
  561.         onTagged: function(doclet, tag) {
  562.             setDocletKindToTitle(doclet, tag);
  563.             setDocletNameToValue(doclet, tag);
  564.             setDocletTypeToValueType(doclet, tag);
  565.         }
  566.     },
  567.     param: {
  568.         canHaveType: true,
  569.         canHaveName: true,
  570.         onTagged: function(doclet, tag) {
  571.             doclet.params = doclet.params || [];
  572.             doclet.params.push(tag.value || {});
  573.         },
  574.         synonyms: ['arg', 'argument']
  575.     },
  576.     private: {
  577.         mustNotHaveValue: true,
  578.         onTagged: function(doclet, tag) {
  579.             doclet.access = 'private';
  580.         }
  581.     },
  582.     property: {
  583.         mustHaveValue: true,
  584.         canHaveType: true,
  585.         canHaveName: true,
  586.         onTagged: function(doclet, tag) {
  587.             doclet.properties = doclet.properties || [];
  588.             doclet.properties.push(tag.value);
  589.         },
  590.         synonyms: ['prop']
  591.     },
  592.     protected: {
  593.         mustNotHaveValue: true,
  594.         onTagged: function(doclet, tag) {
  595.             doclet.access = 'protected';
  596.         }
  597.     },
  598.     public: {
  599.         mustNotHaveValue: true,
  600.         onTagged: function(doclet, tag) {
  601.             doclet.access = 'public';
  602.         }
  603.     },
  604.     readonly: {
  605.         mustNotHaveValue: true,
  606.         onTagged: function(doclet, tag) {
  607.             doclet.readonly = true;
  608.         }
  609.     },
  610.     requires: {
  611.         mustHaveValue: true,
  612.         onTagged: function(doclet, tag) {
  613.             var requiresName;
  615.             // inline link tags are passed through as-is so that `@requires {@link foo}` works
  616.             if ( require('jsdoc/tag/inline').isInlineTag(tag.value, 'link\\S*') ) {
  617.                 requiresName = tag.value;
  618.             }
  619.             // otherwise, assume it's a module
  620.             else {
  621.                 requiresName = firstWordOf(tag.value);
  622.                 if (requiresName.indexOf(MODULE_NAMESPACE) !== 0) {
  623.                     requiresName = MODULE_NAMESPACE + requiresName;
  624.                 }
  625.             }
  627.             doclet.requires = doclet.requires || [];
  628.             doclet.requires.push(requiresName);
  629.         }
  630.     },
  631.     returns: {
  632.         mustHaveValue: true,
  633.         canHaveType: true,
  634.         onTagged: function(doclet, tag) {
  635.             doclet.returns = doclet.returns || [];
  636.             doclet.returns.push(tag.value);
  637.         },
  638.         synonyms: ['return']
  639.     },
  640.     see: {
  641.         mustHaveValue: true,
  642.         onTagged: function(doclet, tag) {
  643.             doclet.see = doclet.see || [];
  644.             doclet.see.push(tag.value);
  645.         }
  646.     },
  647.     since: {
  648.         mustHaveValue: true,
  649.         onTagged: function(doclet, tag) {
  650.             doclet.since = tag.value;
  651.         }
  652.     },
  653.     static: {
  654.         onTagged: function(doclet, tag) {
  655.             setDocletScopeToTitle(doclet, tag);
  656.         }
  657.     },
  658.     summary: {
  659.         mustHaveValue: true,
  660.         onTagged: function(doclet, tag) {
  661.             doclet.summary = tag.value;
  662.         }
  663.     },
  664.     'this': {
  665.         mustHaveValue: true,
  666.         onTagged: function(doclet, tag) {
  667.             doclet.this = firstWordOf(tag.value);
  668.         }
  669.     },
  670.     todo: {
  671.         mustHaveValue: true,
  672.         onTagged: function(doclet, tag) {
  673.             doclet.todo = doclet.todo || [];
  674.             doclet.todo.push(tag.value);
  675.         }
  676.     },
  677.     throws: {
  678.         mustHaveValue: true,
  679.         canHaveType: true,
  680.         onTagged: function(doclet, tag) {
  681.             doclet.exceptions = doclet.exceptions || [];
  682.             doclet.exceptions.push(tag.value);
  683.         },
  684.         synonyms: ['exception']
  685.     },
  686.     tutorial: {
  687.         mustHaveValue: true,
  688.         onTagged: function(doclet, tag) {
  689.             doclet.tutorials = doclet.tutorials || [];
  690.             doclet.tutorials.push(tag.value);
  691.         }
  692.     },
  693.     type: {
  694.         mustHaveValue: true,
  695.         mustNotHaveDescription: true,
  696.         canHaveType: true,
  697.         onTagText: function(text) {
  698.             var closeIdx;
  699.             var openIdx;
  701.             var OPEN_BRACE = '{';
  702.             var CLOSE_BRACE = '}';
  704.             // remove line breaks
  705.             text = text.replace(/[\f\n\r]/g, '');
  707.             // Text must be a type expression; for backwards compatibility, we add braces if they're
  708.             // missing. But do NOT add braces to things like `@type {string} some pointless text`.
  709.             openIdx = text.indexOf(OPEN_BRACE);
  710.             closeIdx = text.indexOf(CLOSE_BRACE);
  712.             // a type expression is at least one character long
  713.             if ( openIdx !== 0 || closeIdx <= openIdx + 1) {
  714.                 text = OPEN_BRACE + text + CLOSE_BRACE;
  715.             }
  717.             return text;
  718.         },
  719.         onTagged: function(doclet, tag) {
  720.             if (tag.value && tag.value.type) {
  721.                 setDocletTypeToValueType(doclet, tag);
  723.                 // for backwards compatibility, we allow @type for functions to imply return type
  724.                 if (doclet.kind === 'function') {
  725.                     doclet.addTag('returns', tag.text);
  726.                 }
  727.             }
  728.         }
  729.     },
  730.     typedef: {
  731.         canHaveType: true,
  732.         canHaveName: true,
  733.         onTagged: function(doclet, tag) {
  734.             setDocletKindToTitle(doclet, tag);
  736.             if (tag.value) {
  737.                 setDocletNameToValueName(doclet, tag);
  739.                 // callbacks are always type {function}
  740.                 if (tag.originalTitle === 'callback') {
  741.                     doclet.type = {
  742.                         names: [
  743.                             'function'
  744.                         ]
  745.                     };
  746.                 }
  747.                 else {
  748.                     setDocletTypeToValueType(doclet, tag);
  749.                 }
  750.             }
  751.         },
  752.         synonyms: ['callback']
  753.     },
  754.     undocumented: {
  755.         mustNotHaveValue: true,
  756.         onTagged: function(doclet, tag) {
  757.             doclet.undocumented = true;
  758.             doclet.comment = '';
  759.         }
  760.     },
  761.     variation: {
  762.         mustHaveValue: true,
  763.         onTagged: function(doclet, tag) {
  764.             var value = tag.value;
  766.             if ( /^\((.+)\)$/.test(value) ) {
  767.                 value = RegExp.$1;
  768.             }
  770.             doclet.variation = value;
  771.         }
  772.     },
  773.     version: {
  774.         mustHaveValue: true,
  775.         onTagged: function(doclet, tag) {
  776.             doclet.version = tag.value;
  777.         }
  778.     }
  779. };
  781. // Tag dictionary for JSDoc.
  782. var jsdocTags = exports.jsdocTags = baseTags;
  784. // Tag dictionary for Google Closure Compiler.
  785. var closureTags = exports.closureTags = {
  786.     const: cloneTagDef(baseTags.constant),
  787.     constructor: cloneTagDef(baseTags.class),
  788.     deprecated: cloneTagDef(baseTags.deprecated),
  789.     enum: cloneTagDef(baseTags.enum),
  790.     extends: cloneTagDef(baseTags.augments),
  791.     final: cloneTagDef(baseTags.readonly),
  792.     implements: cloneTagDef(baseTags.implements),
  793.     inheritdoc: cloneTagDef(baseTags.inheritdoc),
  794.     interface: cloneTagDef(baseTags.interface, {
  795.         canHaveName: false,
  796.         mustNotHaveValue: true
  797.     }),
  798.     lends: cloneTagDef(baseTags.lends),
  799.     license: cloneTagDef(baseTags.license),
  800.     // Closure Compiler only
  801.     override: {
  802.         mustNotHaveValue: true,
  803.         onTagged: function(doclet, tag) {
  804.             doclet.override = true;
  805.         }
  806.     },
  807.     param: cloneTagDef(baseTags.param),
  808.     private: {
  809.         canHaveType: true,
  810.         onTagged: function(doclet, tag) {
  811.             doclet.access = 'private';
  813.             if (tag.value && tag.value.type) {
  814.                 setDocletTypeToValueType(doclet, tag);
  815.             }
  816.         }
  817.     },
  818.     protected: {
  819.         canHaveType: true,
  820.         onTagged: function(doclet, tag) {
  821.             doclet.access = 'protected';
  823.             if (tag.value && tag.value.type) {
  824.                 setDocletTypeToValueType(doclet, tag);
  825.             }
  826.         }
  827.     },
  828.     return: cloneTagDef(baseTags.returns),
  829.     'this': cloneTagDef(baseTags.this),
  830.     throws: cloneTagDef(baseTags.throws),
  831.     type: cloneTagDef(baseTags.type, {
  832.         mustNotHaveDescription: false
  833.     }),
  834.     typedef: cloneTagDef(baseTags.typedef)
  835. };
  837. function addTagDefinitions(dictionary, tagDefs) {
  838.     Object.keys(tagDefs).forEach(function(tagName) {
  839.         var tagDef;
  841.         tagDef = tagDefs[tagName];
  842.         dictionary.defineTag(tagName, tagDef);
  844.         if (tagDef.synonyms) {
  845.             tagDef.synonyms.forEach(function(synonym) {
  846.                 dictionary.defineSynonym(tagName, synonym);
  847.             });
  848.         }
  849.     });
  850. }
  852. /**
  853.  * Populate the given dictionary with the appropriate JSDoc tag definitions.
  854.  *
  855.  * If the `tagDefinitions` parameter is omitted, JSDoc uses its configuration settings to decide
  856.  * which tags to add to the dictionary.
  857.  *
  858.  * If the `tagDefinitions` parameter is included, JSDoc adds only the tag definitions from the
  859.  * `tagDefinitions` object. The configuration settings are ignored.
  860.  *
  861.  * @param {module:jsdoc/tag/dictionary} dictionary
  862.  * @param {Object} [tagDefinitions] - A dictionary whose values define the rules for a JSDoc tag.
  863.  */
  864. exports.defineTags = function(dictionary, tagDefinitions) {
  865.     var dictionaries;
  867.     if (!tagDefinitions) {
  868.         dictionaries = jsdoc.env.conf.tags.dictionaries;
  870.         if (!dictionaries) {
  871.             jsdoc.util.logger.error('The configuration setting "tags.dictionaries" is undefined. ' +
  872.                 'Unable to load tag definitions.');
  873.             return;
  874.         }
  875.         else {
  876.             dictionaries = dictionaries.slice(0).reverse();
  877.         }
  879.         dictionaries.forEach(function(dictName) {
  880.             var tagDefs = exports[DEFINITIONS[dictName]];
  882.             if (!tagDefs) {
  883.                 jsdoc.util.logger.error('The configuration setting "tags.dictionaries" contains ' +
  884.                     'the unknown dictionary name %s. Ignoring the dictionary.', dictName);
  885.                 return;
  886.             }
  888.             addTagDefinitions(dictionary, tagDefs);
  889.         });
  890.     }
  891.     else {
  892.         addTagDefinitions(dictionary, tagDefinitions);
  893.     }
  894. };