<commit_before>/**
 * @license
 * Copyright Google Inc. All Rights Reserved.
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://angular.io/license
 */

import * as ts from 'typescript';

/**
 * TypeScript has an API for JSDoc already, but it's not exposed.
 * https://github.com/Microsoft/TypeScript/issues/7393
 * For now we create types that are similar to theirs so that migrating
 * to their API will be easier.  See e.g. ts.JSDocTag and ts.JSDocComment.
 */
export interface Tag {
  /**
   * tagName is e.g. "param" in an @param declaration.  It is the empty string
   * for the plain text documentation that occurs before any @foo lines.
   */
  tagName: string;
  /**
   * parameterName is the the name of the function parameter, e.g. "foo"
   * in `\@param foo The foo param`
   */
  parameterName?: string;
  /**
   * The type of a JSDoc \@param, \@type etc tag, rendered in curly braces.
   * Can also hold the type of an \@suppress.
   */
  type?: string;
  /** optional is true for optional function parameters. */
  optional?: boolean;
  /** restParam is true for "...x: foo[]" function parameters. */
  restParam?: boolean;
  /**
   * destructuring is true for destructuring bind parameters, which require
   * non-null arguments on the Closure side.  Can likely remove this
   * once TypeScript nullable types are available.
   */
  destructuring?: boolean;
  /** Any remaining text on the tag, e.g. the description. */
  text?: string;
}

/**
 * A list of all JSDoc tags allowed by the Closure compiler.
 * All tags other than these are escaped before emitting.
 *
 * Note that some of these tags are also rejected by tsickle when seen in
 * the user-provided source, but also that tsickle itself may generate some of these.
 * This whitelist is just used for controlling the output.
 *
 * The public Closure docs don't list all the tags it allows; this list comes
 * from the compiler source itself.
 * https://github.com/google/closure-compiler/blob/master/src/com/google/javascript/jscomp/parsing/Annotation.java
 * https://github.com/google/closure-compiler/blob/master/src/com/google/javascript/jscomp/parsing/ParserConfig.properties
 */
const JSDOC_TAGS_OUTPUT_WHITELIST = new Set([
  'abstract',
  'argument',
  'author',
  'const',
  'constant',
  'constructor',
  'copyright',
  'define',
  'deprecated',
  'desc',
  'dict',
  'disposes',
  'enhance',
  'enhanceable',
  'enum',
  'export',
  'expose',
  'extends',
  'externs',
  'fileoverview',
  'final',
  'hassoydelcall',
  'hassoydeltemplate',
  'hidden',
  'id',
  'idGenerator',
  'ignore',
  'implements',
  'implicitCast',
  'inheritDoc',
  'interface',
  'jaggerInject',
  'jaggerModule',
  'jaggerProvide',
  'jaggerProvidePromise',
  'lends',
  'license',
  'link',
  'meaning',
  'modifies',
  'modName',
  'mods',
  'ngInject',
  'noalias',
  'nocollapse',
  'nocompile',
  'nosideeffects',
  'override',
  'owner',
  'package',
  'param',
  'pintomodule',
  'polymer',
  'polymerBehavior',
  'preserve',
  'preserveTry',
  'private',
  'protected',
  'public',
  'record',
  'requirecss',
  'requires',
  'return',
  'returns',
  'see',
  'struct',
  'suppress',
  'template',
  'this',
  'throws',
  'type',
  'typedef',
  'unrestricted',
  'version',
  'wizaction',
  'wizmodule',
]);

/**
 * A list of JSDoc @tags that are never allowed in TypeScript source. These are Closure tags that
 * can be expressed in the TypeScript surface syntax. As tsickle's emit will mangle type names,
 * these will cause Closure Compiler issues and should not be used.
 * Note: 'template' is special-cased below; see where this set is queried.
 */
const JSDOC_TAGS_INPUT_BLACKLIST = new Set([
  'augments', 'class',      'constructs', 'constructor', 'enum',      'extends', 'field',
  'function', 'implements', 'interface',  'lends',       'namespace', 'private', 'public',
  'record',   'static',     'template',   'this',        'type',      'typedef',
]);

/**
 * JSDoc \@tags that might include a {type} after them. Specifying a type is forbidden, since it
 * would collide with TypeScript's type information. If a type *is* given, the entire tag will be
 * ignored.
 */
const JSDOC_TAGS_WITH_TYPES = new Set([
  'const',<commit_msg>forbid '@protected' in TypeScript comments<commit_after>/**
 * @license
 * Copyright Google Inc. All Rights Reserved.
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://angular.io/license
 */

import * as ts from 'typescript';

/**
 * TypeScript has an API for JSDoc already, but it's not exposed.
 * https://github.com/Microsoft/TypeScript/issues/7393
 * For now we create types that are similar to theirs so that migrating
 * to their API will be easier.  See e.g. ts.JSDocTag and ts.JSDocComment.
 */
export interface Tag {
  /**
   * tagName is e.g. "param" in an @param declaration.  It is the empty string
   * for the plain text documentation that occurs before any @foo lines.
   */
  tagName: string;
  /**
   * parameterName is the the name of the function parameter, e.g. "foo"
   * in `\@param foo The foo param`
   */
  parameterName?: string;
  /**
   * The type of a JSDoc \@param, \@type etc tag, rendered in curly braces.
   * Can also hold the type of an \@suppress.
   */
  type?: string;
  /** optional is true for optional function parameters. */
  optional?: boolean;
  /** restParam is true for "...x: foo[]" function parameters. */
  restParam?: boolean;
  /**
   * destructuring is true for destructuring bind parameters, which require
   * non-null arguments on the Closure side.  Can likely remove this
   * once TypeScript nullable types are available.
   */
  destructuring?: boolean;
  /** Any remaining text on the tag, e.g. the description. */
  text?: string;
}

/**
 * A list of all JSDoc tags allowed by the Closure compiler.
 * All tags other than these are escaped before emitting.
 *
 * Note that some of these tags are also rejected by tsickle when seen in
 * the user-provided source, but also that tsickle itself may generate some of these.
 * This whitelist is just used for controlling the output.
 *
 * The public Closure docs don't list all the tags it allows; this list comes
 * from the compiler source itself.
 * https://github.com/google/closure-compiler/blob/master/src/com/google/javascript/jscomp/parsing/Annotation.java
 * https://github.com/google/closure-compiler/blob/master/src/com/google/javascript/jscomp/parsing/ParserConfig.properties
 */
const JSDOC_TAGS_OUTPUT_WHITELIST = new Set([
  'abstract',
  'argument',
  'author',
  'const',
  'constant',
  'constructor',
  'copyright',
  'define',
  'deprecated',
  'desc',
  'dict',
  'disposes',
  'enhance',
  'enhanceable',
  'enum',
  'export',
  'expose',
  'extends',
  'externs',
  'fileoverview',
  'final',
  'hassoydelcall',
  'hassoydeltemplate',
  'hidden',
  'id',
  'idGenerator',
  'ignore',
  'implements',
  'implicitCast',
  'inheritDoc',
  'interface',
  'jaggerInject',
  'jaggerModule',
  'jaggerProvide',
  'jaggerProvidePromise',
  'lends',
  'license',
  'link',
  'meaning',
  'modifies',
  'modName',
  'mods',
  'ngInject',
  'noalias',
  'nocollapse',
  'nocompile',
  'nosideeffects',
  'override',
  'owner',
  'package',
  'param',
  'pintomodule',
  'polymer',
  'polymerBehavior',
  'preserve',
  'preserveTry',
  'private',
  'protected',
  'public',
  'record',
  'requirecss',
  'requires',
  'return',
  'returns',
  'see',
  'struct',
  'suppress',
  'template',
  'this',
  'throws',
  'type',
  'typedef',
  'unrestricted',
  'version',
  'wizaction',
  'wizmodule',
]);

/**
 * A list of JSDoc @tags that are never allowed in TypeScript source. These are Closure tags that
 * can be expressed in the TypeScript surface syntax. As tsickle's emit will mangle type names,
 * these will cause Closure Compiler issues and should not be used.
 * Note: 'template' is special-cased below; see where this set is queried.
 */
const JSDOC_TAGS_INPUT_BLACKLIST = new Set([
  'augments', 'class',      'constructs', 'constructor', 'enum',      'extends', 'field',
  'function', 'implements', 'interface',  'lends',       'namespace', 'private', 'protected', 'public',
  'record',   'static',     'template',   'this',        'type',      'typedef',
]);

/**
 * JSDoc \@tags that might include a {type} after them. Specifying a type is forbidden, since it
 * would collide with TypeScript's type information. If a type *is* given, the entire tag will be
 * ignored.
 */
const JSDOC_TAGS_WITH_TYPES = new Set([
  'const',
{'fraction_non_alphanumeric': 0.1329923273657289, 'fraction_numerical': 0.0009300162752848175, 'mean_word_length': 3.4854014598540144, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '172283', 'n_tokens_mistral': 2810, 'n_tokens_neox': 2765, 'n_words': 946}