Package com.google.javascript.rhino

Class JSDocInfo

java.lang.Object
com.google.javascript.rhino.JSDocInfo
All Implemented Interfaces:
Serializable
public class JSDocInfo extends Object implements Serializable
JSDoc information describing JavaScript code. JSDoc is represented as a unified object with fields for each JSDoc annotation, even though some combinations are incorrect. For instance, if a JSDoc describes an enum, it cannot have information about a return type. This implementation takes advantage of such incompatibilities to reuse fields for multiple purposes, reducing memory consumption.

Constructing JSDocInfo objects is simplified by JSDocInfo.Builder which provides early incompatibility detection.

See Also:

  • Method Details

    • builder

      public static JSDocInfo.Builder builder()
      Create a new JSDocInfo.Builder object.

    • toBuilder

      public JSDocInfo.Builder toBuilder()

    • clone

      public JSDocInfo clone()
      Overrides:
      clone in class Object

    • cloneAndReplaceTypeNames

      public JSDocInfo cloneAndReplaceTypeNames(Set<String> names)
      Clones this JSDoc but replaces the given names in any type related annotation with unknown type.
      Returns:
      returns the the cloned JSDocInfo

    • clone

      public JSDocInfo clone(boolean cloneTypeNodes)

    • areEquivalent

      public static boolean areEquivalent(JSDocInfo jsDoc1, JSDocInfo jsDoc2)

    • isAnyIdGenerator

      public boolean isAnyIdGenerator()
      Returns whether any @idGenerator or idGenerator {?} annotation is present.

    • isConsistentIdGenerator

      public boolean isConsistentIdGenerator()
      Returns whether the @idGenerator {consistent} is present on this JSDocInfo.

    • isStableIdGenerator

      public boolean isStableIdGenerator()
      Returns whether the @idGenerator {stable} is present on this JSDocInfo.

    • isXidGenerator

      public boolean isXidGenerator()
      Returns whether the @idGenerator {xid} is present on this JSDocInfo.

    • isMappedIdGenerator

      public boolean isMappedIdGenerator()
      Returns whether the @idGenerator {mapped} is present on this JSDocInfo.

    • isIdGenerator

      public boolean isIdGenerator()
      Returns whether the @idGenerator is present on this JSDocInfo.

    • isConstant

      public boolean isConstant()
      Returns whether this JSDocInfo implies that annotated value is constant.

    • hasConstAnnotation

      public boolean hasConstAnnotation()
      Returns whether the @const annotation is present on this JSDocInfo.

    • isFinal

      public boolean isFinal()
      Returns whether the @final annotation is present on this JSDocInfo.

    • isConstructor

      public boolean isConstructor()
      Returns whether the @constructor annotation is present on this JSDocInfo.

    • isAbstract

      public boolean isAbstract()
      Returns whether the @abstract annotation is present on this JSDocInfo.

    • usesImplicitMatch

      public boolean usesImplicitMatch()
      Returns whether the @record annotation is present on this JSDocInfo.

    • makesUnrestricted

      public boolean makesUnrestricted()
      Returns whether the @unrestricted annotation is present on this JSDocInfo.

    • makesStructs

      public boolean makesStructs()
      Returns whether the @struct annotation is present on this JSDocInfo.

    • makesDicts

      public boolean makesDicts()
      Returns whether the @dict annotation is present on this JSDocInfo.

    • isDefine

      public boolean isDefine()
      Returns whether the @define annotation is present on this JSDocInfo. If this annotation is present, then the getType() method will retrieve the define type.

    • isOverride

      public boolean isOverride()
      Returns whether the @override annotation is present on this JSDocInfo.

    • isDeprecated

      public boolean isDeprecated()
      Returns whether the @deprecated annotation is present on this JSDocInfo.

    • isInterface

      public boolean isInterface()
      Returns whether the @interface annotation is present on this JSDocInfo.

    • isConstructorOrInterface

      public boolean isConstructorOrInterface()

    • isExport

      public boolean isExport()
      Returns whether the @export annotation is present on this JSDocInfo.

    • isImplicitCast

      public boolean isImplicitCast()
      Returns whether the @implicitCast annotation is present on this JSDocInfo.

    • isNoSideEffects

      public boolean isNoSideEffects()
      Returns whether the @nosideeffects annotation is present on this JSDocInfo.

    • isExterns

      public boolean isExterns()
      Returns whether the @externs annotation is present on this JSDocInfo.

    • isNoCoverage

      public boolean isNoCoverage()
      Returns whether the @nocoverage annotation is present on this JSDocInfo.

    • isTypeSummary

      public boolean isTypeSummary()
      Returns whether the @typeSummary annotation is present on this JSDocInfo.

    • isNoCompile

      public boolean isNoCompile()
      Returns whether the @nocompile annotation is present on this JSDocInfo.

    • isNoDts

      public boolean isNoDts()
      Returns whether the @nodts annotation is present on this JSDocInfo.

    • isNoCollapse

      public boolean isNoCollapse()
      Returns whether the @nocollapse annotation is present on this JSDocInfo.

    • isNoInline

      public boolean isNoInline()
      Returns whether the @noinline annotation is present on this JSDocInfo.

    • isRequireInlining

      public boolean isRequireInlining()
      Returns whether the @requireInlining annotation is present on this JSDocInfo.

    • isCollapsibleOrBreakMyCode

      public boolean isCollapsibleOrBreakMyCode()
      Returns whether the @collapsibleOrBreakMyCode annotation is present on this JSDocInfo.

    • isPureOrBreakMyCode

      public boolean isPureOrBreakMyCode()
      Returns whether the @pureOrBreakMyCode annotation is present on this JSDocInfo.

    • isProvideGoog

      public boolean isProvideGoog()
      Returns whether the @provideGoog annotation is present on this JSDocInfo.

    • isProvideAlreadyProvided

      public boolean isProvideAlreadyProvided()
      Returns whether the @provideAlreadyProvided annotation is present on this JSDocInfo.

    • containsDeclarationExcludingTypelessConst

      public boolean containsDeclarationExcludingTypelessConst()
      Returns whether there is a declaration present on this JSDocInfo.

      Does not consider `@const` (without a following type) to indicate a declaration. Whether you want this method, or the`containsDeclaration` that includes const, depends on whether you want to consider /** @const * / a.b.c = 0 a declaration or not.

    • containsTypeDeclaration

      public boolean containsTypeDeclaration()
      Returns whether this JSDoc contains a type declaration such as /** @type {string}

    • containsDeclaration

      public boolean containsDeclaration()
      Returns whether there is a declaration present on this JSDocInfo, including a typeless @const like /** @const * / a.b.c = 0

    • containsFunctionDeclaration

      @Deprecated public boolean containsFunctionDeclaration()
      Deprecated.
      This method is quite heuristic, looking for @type annotations that start with "function". Other methods like containsDeclaration() and containsTypeDefinition are generally preferred.
      Returns:
      Whether there is a declaration of a callable type.

    • containsTypeDefinition

      public boolean containsTypeDefinition()

    • isAtSignCodePresent

      public boolean isAtSignCodePresent()
      Returns whether the @code is present within this JSDocInfo.

    • getVisibility

      public JSDocInfo.Visibility getVisibility()
      Gets the visibility specified by @private, @protected or @public annotation. If no visibility is specified, visibility is inherited from the base class.

    • getParameterType

      public @Nullable JSTypeExpression getParameterType(String parameter)
      Gets the type of a given named parameter.
      Parameters:
      parameter - the parameter's name
      Returns:
      the parameter's type or null if this parameter is not defined or has a null type

    • hasParameter

      public boolean hasParameter(String parameter)
      Returns whether the parameter is defined.

    • hasParameterType

      public boolean hasParameterType(String parameter)
      Returns whether the parameter has an attached type.
      Returns:
      true if the parameter has an attached type, false if the parameter has no attached type or does not exist.

    • getParameterNames

      public Set<String> getParameterNames()
      Returns the set of names of the defined parameters. The iteration order of the returned set is the order in which parameters are defined in the JSDoc, rather than the order in which the function declares them.
      Returns:
      the set of names of the defined parameters. The returned set is immutable.

    • getParameterNameAt

      public @Nullable String getParameterNameAt(int index)
      Returns the nth name in the defined parameters. The iteration order is the order in which parameters are defined in the JSDoc, rather than the order in which the function declares them.

    • getParameterCount

      public int getParameterCount()
      Gets the number of parameters defined.

    • getThrowsAnnotations

      public List<String> getThrowsAnnotations()
      Returns the list of thrown types and descriptions as text.

    • hasEnumParameterType

      public boolean hasEnumParameterType()
      Returns whether an enum parameter type, specified using the @enum annotation, is present on this JSDoc.

    • hasTypedefType

      public boolean hasTypedefType()
      Returns whether a typedef parameter type, specified using the @typedef annotation, is present on this JSDoc.

    • hasReturnType

      public boolean hasReturnType()
      Returns whether this JSDocInfo contains a type for @return annotation.

    • hasType

      public boolean hasType()
      Returns whether a type, specified using the @type annotation, is present on this JSDoc.

    • hasTypeInformation

      public boolean hasTypeInformation()

    • isInlineType

      public boolean isInlineType()
      Returns whether the type annotation was inlined.

    • getReturnType

      public JSTypeExpression getReturnType()
      Gets the return type specified by the @return annotation.

    • getEnumParameterType

      public JSTypeExpression getEnumParameterType()
      Gets the enum parameter type specified by the @enum annotation.

    • getTypedefType

      public JSTypeExpression getTypedefType()
      Gets the typedef type specified by the @type annotation.

    • getType

      public JSTypeExpression getType()
      Gets the type specified by the @type annotation.

    • getThisType

      public JSTypeExpression getThisType()
      Gets the type specified by the @this annotation.

    • hasThisType

      public boolean hasThisType()
      Returns whether this JSDocInfo contains a type for @this annotation.

    • getBaseType

      public JSTypeExpression getBaseType()
      Gets the base type specified by the @extends annotation.

    • getDescription

      public String getDescription()
      Gets the description specified by the @desc annotation.

    • getTsTypes

      public com.google.common.collect.ImmutableList<String> getTsTypes()
      Gets the ts type declarations specified by the @tsType annotations.

    • getMeaning

      public String getMeaning()
      Gets the meaning specified by the @meaning annotation.

      In localization systems, two messages with the same content but different "meanings" may be translated differently. By default, we use the name of the variable that the message is initialized to as the "meaning" of the message.

      But some code generators (like Closure Templates) inject their own meaning with the jsdoc @meaning annotation.

    • getAlternateMessageId

      public String getAlternateMessageId()
      Gets the alternate message ID specified by the @alternateMessageId annotation.

      In localization systems, if we migrate from one message ID algorithm to another, we can specify the old one via @alternateMessageId. This allows the product to use the previous translation while waiting for the new one to be translated.

      Some code generators (like Closure Templates) inject this.

    • getLendsName

      public JSTypeExpression getLendsName()
      Gets the name we're lending to in a @lends annotation.

      In many reflection APIs, you pass an anonymous object to a function, and that function mixes the anonymous object into another object. The @lends annotation allows the type system to track those property assignments.

    • hasLendsName

      public boolean hasLendsName()

    • getClosurePrimitiveId

      public String getClosurePrimitiveId()
      Returns the @closurePrimitive {id} identifier

    • hasClosurePrimitiveId

      public boolean hasClosurePrimitiveId()
      Whether this JSDoc is annotated with @closurePrimitive

    • isNgInject

      public boolean isNgInject()
      Returns whether JSDoc is annotated with @ngInject annotation.

    • isWizaction

      public boolean isWizaction()
      Returns whether JSDoc is annotated with @wizaction annotation.

    • isWizcallback

      public boolean isWizcallback()
      Returns if JSDoc is annotated with @wizcallback annotation.

    • isPolymerBehavior

      public boolean isPolymerBehavior()
      Returns whether JSDoc is annotated with @polymerBehavior annotation.

    • isPolymer

      public boolean isPolymer()
      Returns whether JSDoc is annotated with @polymer annotation.

    • isCustomElement

      public boolean isCustomElement()
      Returns whether JSDoc is annotated with @customElement annotation.

    • isMixinClass

      public boolean isMixinClass()
      Returns whether JSDoc is annotated with @mixinClass annotation.

    • isMixinFunction

      public boolean isMixinFunction()
      Returns whether JSDoc is annotated with @mixinFunction annotation.

    • isSassGeneratedCssTs

      public boolean isSassGeneratedCssTs()

    • isClosureUnawareCode

      public boolean isClosureUnawareCode()
      Returns whether JSDoc is annotated with the @closureUnawareCode annotation.

    • isUsedViaDotConstructor

      public boolean isUsedViaDotConstructor()
      Returns whether JSDoc is annotated with the @usedViaDotConstructor annotation.

    • getLicense

      public String getLicense()
      Gets the description specified by the @license annotation.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toStringVerbose

      public String toStringVerbose()

    • hasBaseType

      public boolean hasBaseType()
      Returns whether this JSDocInfo contains a type for @extends annotation.

    • getImplementedInterfaces

      public List<JSTypeExpression> getImplementedInterfaces()
      Returns the types specified by the @implements annotation.
      Returns:
      An immutable list of JSTypeExpression objects that can be resolved to types.

    • getImplementedInterfaceCount

      public int getImplementedInterfaceCount()
      Gets the number of interfaces specified by the @implements annotation.

    • getExtendedInterfaces

      public List<JSTypeExpression> getExtendedInterfaces()
      Returns the interfaces extended by an interface
      Returns:
      An immutable list of JSTypeExpression objects that can be resolved to types.

    • getExtendedInterfacesCount

      public int getExtendedInterfacesCount()
      Gets the number of extended interfaces specified

    • getDeprecationReason

      public String getDeprecationReason()
      Returns the deprecation reason or null if none specified.

    • getSuppressions

      public Set<String> getSuppressions()
      Returns the set of suppressed warnings.

    • getSuppressionsAndTheirDescription

      public com.google.common.collect.ImmutableMap<com.google.common.collect.ImmutableSet<String>,String> getSuppressionsAndTheirDescription()
      Returns a map containing key=set of suppressions, and value=the corresponding description for the set.

    • getModifies

      public Set<String> getModifies()
      Returns the set of sideeffect notations.

    • hasDescriptionForParameter

      public boolean hasDescriptionForParameter(String name)
      Returns whether a description exists for the parameter with the specified name.

    • getDescriptionForParameter

      public @Nullable String getDescriptionForParameter(String name)
      Returns the description for the parameter with the given name, if its exists.

    • getAuthors

      public List<String> getAuthors()
      Returns the list of authors or null if none.

    • getReferences

      public List<String> getReferences()
      Returns the list of references or null if none.

    • getReturnDescription

      public String getReturnDescription()
      Returns the description of the returned object or null if none specified.

    • getBlockDescription

      public String getBlockDescription()
      Returns the block-level description or null if none specified.

    • hasFileOverview

      public boolean hasFileOverview()
      Returns whether this has a fileoverview flag.

    • getFileOverview

      public String getFileOverview()
      Returns the file overview or null if none specified.

    • hasEnhance

      public boolean hasEnhance()
      Returns whether this has an enhanced namespace.

    • getEnhance

      public String getEnhance()
      Returns the enhanced namespace or null if none is specified.

    • hasMods

      public boolean hasMods()
      Returns whether this has a modded namespace.

    • getMods

      public String getMods()
      Returns the modded namespace or null if none is specified.

    • getMarkers

      public Collection<JSDocInfo.Marker> getMarkers()
      Gets the list of all markers for the documentation in this JSDoc.

    • getTemplateTypeNames

      public com.google.common.collect.ImmutableList<String> getTemplateTypeNames()
      Gets the @template type names.

      Excludes @template types from TTL; get those with getTypeTransformations()

    • getTemplateTypes

      public com.google.common.collect.ImmutableMap<String,JSTypeExpression> getTemplateTypes()

    • getTypeTransformations

      public com.google.common.collect.ImmutableMap<String,Node> getTypeTransformations()
      Gets the type transformations.

    • getTypeExpressions

      public Collection<JSTypeExpression> getTypeExpressions()
      Returns a collection of all JSTypeExpressions that are a part of this JSDocInfo.

      This includes:

      • base type
      • @extends
      • @implements
      • @lend
      • @param
      • @return
      • @template
      • @this
      • @throws
      • @type
      Any future type specific JSDoc should make sure to add the appropriate nodes here.
      Returns:
      collection of all type nodes

    • getTypeNodes

      public Collection<Node> getTypeNodes()
      Returns a collection of all type nodes that are a part of this JSDocInfo.

      This includes:

      • @extends
      • @implements
      • @lend
      • @param
      • @return
      • @template
      • @this
      • @throws
      • @type
      Any future type specific JSDoc should make sure to add the appropriate nodes here.
      Returns:
      collection of all type nodes

    • hasModifies

      public boolean hasModifies()

    • getOriginalCommentString

      public String getOriginalCommentString()
      Returns the original JSDoc comment string. Returns null unless parseJsDocDocumentation is enabled via the ParserConfig.

    • getOriginalCommentPosition

      public int getOriginalCommentPosition()

    • modifiesThis

      public boolean modifiesThis()
      Get the value of the @modifies{this} annotation stored in the doc info.

    • hasSideEffectsArgumentsAnnotation

      public boolean hasSideEffectsArgumentsAnnotation()
      Returns whether the @modifies annotation includes "arguments" or any named parameters.

    • getLogTypeInCompiler

      public boolean getLogTypeInCompiler()
      Returns whether we should log the type of values passed to this function.

    • getPropertyValueByIndex

      protected Object getPropertyValueByIndex(int index)