• Home
• com.google.javascript
• closure-compiler-unshaded
• v20230103
• source code
• InferJSDocInfo.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

com.google.javascript.jscomp.InferJSDocInfo Maven / Gradle / Ivy

/*
 * Copyright 2009 The Closure Compiler Authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.javascript.jscomp;


import com.google.javascript.jscomp.NodeTraversal.AbstractPostOrderCallback;
import com.google.javascript.rhino.JSDocInfo;
import com.google.javascript.rhino.Node;
import com.google.javascript.rhino.jstype.FunctionType;
import com.google.javascript.rhino.jstype.JSType;
import com.google.javascript.rhino.jstype.ObjectType;
import org.jspecify.nullness.Nullable;

/**
 * Sets the {@link JSDocInfo} on all {@code JSType}s, including their properties, using the JSDoc on
 * the node defining that type or property.
 *
 * 
This pass propagates JSDocs across the type graph, but not across the symbol graph. For
 * example:
 *
 * 
{@code
 * /**
 *  * I'm a user type!
 *  * @constructor
 *  *\/
 * var Foo = function() { };
 *
 * var Bar = Foo;
 * }
 *
 * will assign the "I'm a user type!" JSDoc from the `Foo` node to type "Foo" and type "ctor{Foo}".
 * However, this pass says nothing about JSDocs being propagated to the `Bar` node.
 *
 * 
JSDoc is initially attached to AST Nodes at parse time. There are 3 cases where JSDocs get
 * attached to the type system, always from the associated declaration node:
 *
 * 

 *   
Nominal types (e.g. constructors, interfaces, enums).
 *   
Object type properties (e.g. `Foo.prototype.bar`).
 *   
Anonymous structural types, including functions. (Some function types with the same
 *       signature are unique and therefore can have distinct JSDocs.) (b/111070482: it's unclear
 *       why we support this.)
 * 
 *
 * 
#1 is fairly straight-forward with the additional detail that JSDocs are propagated to both
 * the instance type and the declaration type (i.e. the ctor or enum type). #2 should also
 * be mostly self-explanatory; it covers scenarios like the following:
 *
 * 
{@code
 * /**
 *  * I'm a method!
 *  * @param {number} x
 *  * @return {number}
 *  *\/
 * Foo.prototype.bar = function(x) { ... };
 * }
 *
 * in which JSDocInfo will appear on the "bar" slot of `Foo.prototype` and `Foo`. The function type
 * used as the RHS of the assignments (i.e. `function(this:Foo, number): number`) is not considered.
 * Note that this example would work equally well if `bar` were declared abstract. #3 is a bit
 * trickier; it covers types such as the following declarations:
 *
 * 
{@code
 * /** I'm an anonymous structural object type! *\/
 * var myObject = {a: 5, b: 'Hello'};
 *
 * /**
 *  * I'm an anonymous structural function type!
 *  * @param {number} x
 *  * @return {string}
 *  *\/
 * var myFunction = function(x) { ... };
 *
 * }
 *
 * which define unique types with their own JSDoc attributes. Object literal or function types with
 * the same structure will get different JSDocs despite possibly comparing equal. Additionally, when
 * assigning instances of these types as properties of nominal types (e.g. using `myFunction` as the
 * RHS of #2) the structural type JSDoc plays no part.
 */
class InferJSDocInfo extends AbstractPostOrderCallback implements CompilerPass {
  private final AbstractCompiler compiler;

  InferJSDocInfo(AbstractCompiler compiler) {
    this.compiler = compiler;
  }

  @Override
  public void process(Node externs, Node root) {
    if (externs != null) {
      NodeTraversal.traverse(compiler, externs, this);
    }
    if (root != null) {
      NodeTraversal.traverse(compiler, root, this);
    }
  }

  @Override
  public void visit(NodeTraversal t, Node n, Node parent) {
    switch (n.getToken()) {
        // Infer JSDocInfo on types of all type declarations on variables.
      case NAME:
        inferJSDocForName(n, parent);
        return;

      case STRING_KEY:
      case GETTER_DEF:
      case SETTER_DEF:
      case MEMBER_FUNCTION_DEF:
      case MEMBER_FIELD_DEF:
        inferJSDocForObjectKeyOrClassField(n, parent);
        return;

      case GETPROP:
        inferJSDocForProperty(n, parent);
        return;

      default:
        return;
    }
  }

  private void inferJSDocForName(Node n, Node parent) {
    if (parent == null) {
      return;
    }

    // Only allow JSDoc on variable declarations, named functions, named classes, and assigns.
    final JSDocInfo typeDoc;
    final JSType aliasedType; // if the right-hand side is a qualified name, its type
    final JSType inferredType;
    if (NodeUtil.isNameDeclaration(parent)) {
      // Case: `/** ... */ (var|let|const) x = function() { ... }`.
      // Case: `(var|let|const) /** ... */ x = function() { ... }`.
      JSDocInfo nameInfo = n.getJSDocInfo();
      typeDoc = (nameInfo != null) ? nameInfo : parent.getJSDocInfo();

      inferredType = n.getJSType();
      // Example: for `const y = x.y;`, the type of `x.y`.
      Node value = n.getFirstChild();
      aliasedType = value != null && value.isQualifiedName() ? value.getJSType() : null;
    } else if (NodeUtil.isFunctionDeclaration(parent) || NodeUtil.isClassDeclaration(parent)) {
      // Case: `/** ... */ function f() { ... }`.
      // Case: `/** ... */ class Foo() { ... }`.
      typeDoc = parent.getJSDocInfo();
      inferredType = parent.getJSType();
      aliasedType = null; // the value is definitely a class or function, not a qualified name.
    } else if (parent.isAssign() && n.isFirstChildOf(parent)) {
      typeDoc = parent.getJSDocInfo();
      inferredType = n.getJSType();
      // Example: y = x.y;
      Node value = n.getNext();
      aliasedType = value.isQualifiedName() ? value.getJSType() : null;
    } else {
      return;
    }

    if (typeDoc == null) {
      return;
    }

    ObjectType objType = dereferenced(inferredType);
    if (shouldAttachJSDocToNominalTypeOrShape(objType, aliasedType)) {
      attachJSDocInfoToNominalTypeOrShape(objType, typeDoc, n.getString());
    }
  }

  private void inferJSDocForObjectKeyOrClassField(Node n, Node parent) {
    JSDocInfo typeDoc = n.getJSDocInfo();
    if (typeDoc == null) {
      return;
    }

    final ObjectType owningType;
    if (parent.isClassMembers()) {
      FunctionType ctorType = JSType.toMaybeFunctionType(parent.getParent().getJSType());
      if (ctorType == null) {
        return;
      }

      if (n.isStaticMember()) {
        owningType = ctorType;
      } else if (n.isMemberFieldDef()) {
        owningType = ctorType.getInstanceType();
      } else {
        owningType = ctorType.getPrototype();
      }
    } else {
      owningType = dereferenced(parent.getJSType());
    }
    if (owningType == null) {
      return;
    }

    String propName = n.getString();
    if (owningType.hasOwnProperty(propName) && owningType.getPropertyJSDocInfo(propName) == null) {
      owningType.setPropertyJSDocInfo(propName, typeDoc);
    }

    // NOTE(lharker): it seems surprising that this doesn't also call
    // attachJSDocInfoToNominalTypeOrShape. I don't know for sure this is a bug, but leaving a
    // comment to document that this is probably not intentional.
  }

  private void inferJSDocForProperty(Node n, Node parent) {
    // Infer JSDocInfo on properties.
    // There are two ways to write doc comments on a property.
    final JSDocInfo typeDoc;
    final JSType aliasedType; // if the rhs is a qualified name, its type
    if (parent.isAssign() && n.isFirstChildOf(parent)) {
      // Case: `/** @deprecated */ obj.prop = ...;`
      typeDoc = parent.getJSDocInfo();
      Node rhs = n.getNext();
      // Example: for `/** @deprecated */ obj.prop = obj.newProp;`, the type of `obj.newProp`.
      aliasedType = rhs.isQualifiedName() ? rhs.getJSType() : null;
    } else if (parent.isExprResult()) {
      // Case: `/** @deprecated */ obj.prop;`
      typeDoc = n.getJSDocInfo();
      aliasedType = null; // there's no value being assigned here
    } else {
      return;
    }

    if (typeDoc == null || !typeDoc.containsDeclaration()) {
      return;
    }

    ObjectType lhsType = dereferenced(n.getFirstChild().getJSType());
    if (lhsType == null) {
      return;
    }

    // Put the JSDoc in the property slot, if there is one.
    String propName = n.getString();
    if (lhsType.hasOwnProperty(propName) && lhsType.getPropertyJSDocInfo(propName) == null) {
      lhsType.setPropertyJSDocInfo(propName, typeDoc);
    }

    ObjectType propType = dereferenced(lhsType.getPropertyType(propName));
    if (shouldAttachJSDocToNominalTypeOrShape(propType, aliasedType)) {
      attachJSDocInfoToNominalTypeOrShape(propType, typeDoc, n.getQualifiedName());
    }
  }

  /** Nullsafe wrapper for {@code JSType#dereference()}. */
  private static @Nullable ObjectType dereferenced(@Nullable JSType type) {
    return type == null ? null : type.dereference();
  }

  /**
   * @param type the type to which we're considering attaching JSDoc, or null
   * @param aliasedType if not null, the JSType of the qualified name on the right-hand side of this
   *     assignment. e.g. for `const x = y;`, the type of `y`. null if there's no value (e.g. `let
   *     x;` with no right-hand side) or if the right-hand side is not a qualified name (e.g. `const
   *     C = class {};` or `const result = fn();`).
   */
  private static boolean shouldAttachJSDocToNominalTypeOrShape(
      @Nullable ObjectType type, @Nullable JSType aliasedType) {
    // If we have no type, or the type already has a JSDocInfo, then no need to attach `typeDoc`.
    // Also check if we're just aliasing something else's type rather than defining a new type.
    // For example, consider this declaration:
    //   /** @const */
    //   var cbAlias = cb;
    // This is a declaration of the name `cbAlias` but doesn't declare a new type. So `type` should
    // equal `aliasedType`, and we shouldn't attach the `/** @const */`
    // JSDoc to the type of `cb`.
    return type != null && type.getJSDocInfo() == null && !type.equals(aliasedType);
  }

  /** Handle cases #1 and #3 in the class doc. */
  private static void attachJSDocInfoToNominalTypeOrShape(
      ObjectType objType, JSDocInfo docInfo, @Nullable String qName) {

    if (objType.isConstructor() || objType.isInterface()) {
      if (!isReferenceNameOf(objType, qName)) {
        return;
      }

      objType.setJSDocInfo(docInfo);
      JSType.toMaybeFunctionType(objType).getInstanceType().setJSDocInfo(docInfo);
    } else if (objType.isEnumType()) {
      // Given: `/** @enum {number} */ MyEnum = { FOO: 0 };`
      // Then: typeOf(MyEnum).referenceName() == "enum{MyEnum}"
      // Then: typeOf(MyEnum.FOO).referenceName() == "MyEnum"
      ObjectType elementType = objType.toMaybeEnumType().getElementsType();
      if (!isReferenceNameOf(elementType, qName)) {
        return;
      }

      objType.setJSDocInfo(docInfo);
      elementType.setJSDocInfo(docInfo);
    } else if (!objType.isNativeObjectType() && objType.isFunctionType()) {
      // Anonymous function types identified by their parameter and return types. Remember there can
      // be many unique but equal instances.
      objType.setJSDocInfo(docInfo);
    }
  }

  private static boolean isReferenceNameOf(ObjectType type, String name) {
    return type.hasReferenceName() && type.getReferenceName().equals(name);
  }
}