com.google.javascript.rhino.JSDocInfo Java Examples

/**
 * Get the JSDocInfo for a function.
 */
static JSDocInfo getFunctionInfo(Node n) {
  Preconditions.checkState(n.getType() == Token.FUNCTION);
  JSDocInfo fnInfo = n.getJSDocInfo();
  if (fnInfo == null && NodeUtil.isFunctionExpression(n)) {
    // Look for the info on other nodes.
    Node parent = n.getParent();
    if (parent.getType() == Token.ASSIGN) {
      // on ASSIGNs
      fnInfo = parent.getJSDocInfo();
    } else if (parent.getType() == Token.NAME) {
      // on var NAME = function() { ... };
      fnInfo = parent.getParent().getJSDocInfo();
    }
  }
  return fnInfo;
}
 

private void checkNoTypeCheckSection(Node n, boolean enterSection) {
  switch (n.getType()) {
    case Token.SCRIPT:
    case Token.BLOCK:
    case Token.VAR:
    case Token.FUNCTION:
    case Token.ASSIGN:
      JSDocInfo info = n.getJSDocInfo();
      if (info != null && info.isNoTypeCheck()) {
        if (enterSection) {
          noTypeCheckSection++;
        } else {
          noTypeCheckSection--;
        }
      }
      validator.setShouldReport(noTypeCheckSection == 0);
      break;
  }
}
 

/**
 * Get the JSDocInfo for a function.
 */
static JSDocInfo getFunctionInfo(Node n) {
  Preconditions.checkState(n.getType() == Token.FUNCTION);
  JSDocInfo fnInfo = n.getJSDocInfo();
  if (fnInfo == null && NodeUtil.isFunctionExpression(n)) {
    // Look for the info on other nodes.
    Node parent = n.getParent();
    if (parent.getType() == Token.ASSIGN) {
      // on ASSIGNs
      fnInfo = parent.getJSDocInfo();
    } else if (parent.getType() == Token.NAME) {
      // on var NAME = function() { ... };
      fnInfo = parent.getParent().getJSDocInfo();
    }
  }
  return fnInfo;
}
 

private boolean isExternAlias(JSType type, JSDocInfo info) {
  if (externTypes.contains(type)) {
    return true;
  }

  // If something is typed as {function(new: Foo)}, it will actually be represented as
  // {function(new: Foo): ?}, which is different than the real constructor. We can get the real
  // constructor, however, with a little type manipulation.
  if (type.isConstructor() && type.toMaybeFunctionType() != null) {
    JSType ctorType = type.toMaybeFunctionType().getInstanceType().getConstructor();
    if (externTypes.contains(ctorType)) {
      return true;
    }
  }

  if (info != null && info.getTypedefType() != null) {
    JSTypeExpression expression = info.getTypedefType();
    type = Types.evaluate(expression, compiler.getTopScope(), compiler.getTypeRegistry());
    return externTypes.contains(type);
  }

  return false;
}
 

private void checkNoTypeCheckSection(Node n, boolean enterSection) {
  switch (n.getType()) {
    case Token.SCRIPT:
    case Token.BLOCK:
    case Token.VAR:
    case Token.FUNCTION:
    case Token.ASSIGN:
      JSDocInfo info = n.getJSDocInfo();
      if (info != null && info.isNoTypeCheck()) {
        if (enterSection) {
          noTypeCheckSection++;
        } else {
          noTypeCheckSection--;
        }
      }
      validator.setShouldReport(noTypeCheckSection == 0);
      break;
  }
}
 

private void maybeSetInlineTypeExpression(
    Node nameNode, Node commentNode, JSDocInfo docInfo, boolean isReturnType) {
  if (docInfo == null) {
    return;
  }
  JSTypeExpression type = docInfo.getType();
  if (type == null) {
    return;
  }
  setTypeExpression(nameNode, type, isReturnType);
  // Remove the part of comment that sets the inline type.
  String toRemove = docInfo.getOriginalCommentString();
  List<GeneralComment> comments = nodeComments.getComments(commentNode);
  if (comments == null) {
    return;
  }

  List<GeneralComment> newComments = Lists.newArrayList();
  for (GeneralComment c : comments) {
    String newText = c.getText().replaceFirst("\\n?" + Pattern.quote(toRemove), "");
    newComments.add(GeneralComment.from(newText, c.getOffset()));
  }

  nodeComments.setComments(commentNode, newComments);
  compiler.reportChangeToEnclosingScope(commentNode);
}
 

/**
 * Returns the super class of the given type that has a constructor.
 */
private JSType getFinalParentClass(JSType type) {
  if (type != null) {
    ObjectType iproto = ObjectType.cast(type).getImplicitPrototype();
    while (iproto != null && iproto.getConstructor() == null) {
      iproto = iproto.getImplicitPrototype();
    }
    if (iproto != null) {
      Node source = iproto.getConstructor().getSource();
      JSDocInfo jsDoc = source != null ? NodeUtil.getBestJSDocInfo(source) : null;
      if (jsDoc != null && jsDoc.isConstant()) {
        return iproto;
      }
    }
  }
  return null;
}
 

private void maybeCollectMember(NodeTraversal t,
    Node member, Node nodeWithJsDocInfo, @Nullable Node value) {
  JSDocInfo info = nodeWithJsDocInfo.getJSDocInfo();

  // Do nothing if there is no JSDoc type info, or
  // if the node is not a member expression, or
  // if the member expression is not of the form: this.someProperty.
  if (info == null ||
      !member.isGetProp() ||
      !member.getFirstChild().isThis()) {
    return;
  }

  member.getFirstChild().setJSType(thisType);
  JSType jsType = getDeclaredType(t.getSourceName(), info, member, value);
  Node name = member.getLastChild();
  if (jsType != null &&
      (name.isName() || name.isString())) {
    thisType.defineDeclaredProperty(
        name.getString(),
        jsType,
        member);
  }
}
 

/**
 * Get the JSDocInfo for a function.
 */
static JSDocInfo getFunctionInfo(Node n) {
  Preconditions.checkState(n.getType() == Token.FUNCTION);
  JSDocInfo fnInfo = n.getJSDocInfo();
  if (fnInfo == null && NodeUtil.isFunctionExpression(n)) {
    // Look for the info on other nodes.
    Node parent = n.getParent();
    if (parent.getType() == Token.ASSIGN) {
      // on ASSIGNs
      fnInfo = parent.getJSDocInfo();
    } else if (parent.getType() == Token.NAME) {
      // on var NAME = function() { ... };
      fnInfo = parent.getParent().getJSDocInfo();
    }
  }
  return fnInfo;
}
 

/**
 * Determines whether the given name is visible in the current context.
 * @param t The current traversal.
 * @param name The name node.
 */
private void checkNameVisibility(NodeTraversal t, Node name, Node parent) {
  Var var = t.getScope().getVar(name.getString());
  if (var != null) {
    JSDocInfo docInfo = var.getJSDocInfo();
    if (docInfo != null) {
      // If a name is private, make sure that we're in the same file.
      Visibility visibility = docInfo.getVisibility();
      if (visibility == Visibility.PRIVATE &&
          !t.getInput().getName().equals(docInfo.getSourceName())) {
        if (docInfo.isConstructor() &&
            isValidPrivateConstructorAccess(parent)) {
          return;
        }

        compiler.report(
            t.makeError(name, BAD_PRIVATE_GLOBAL_ACCESS,
                name.getString(), docInfo.getSourceName()));
      }
    }
  }
}
 

/**
 * Get the JSDocInfo for a function.
 */
public static JSDocInfo getFunctionJSDocInfo(Node n) {
  Preconditions.checkState(n.getType() == Token.FUNCTION);
  JSDocInfo fnInfo = n.getJSDocInfo();
  if (fnInfo == null && NodeUtil.isFunctionExpression(n)) {
    // Look for the info on other nodes.
    Node parent = n.getParent();
    if (parent.getType() == Token.ASSIGN) {
      // on ASSIGNs
      fnInfo = parent.getJSDocInfo();
    } else if (parent.getType() == Token.NAME) {
      // on var NAME = function() { ... };
      fnInfo = parent.getParent().getJSDocInfo();
    }
  }
  return fnInfo;
}
 

/**
 * Warns about any references to "this" in the given FUNCTION. The function
 * is getting collapsed, so the references will change.
 */
private void checkForHosedThisReferences(Node function, JSDocInfo docInfo,
    final Name name) {
  // A function is getting collapsed. Make sure that if it refers to
  // "this", it must be a constructor or documented with @this.
  if (docInfo == null ||
      (!docInfo.isConstructor() && !docInfo.hasThisType())) {
    NodeTraversal.traverse(compiler, function.getLastChild(),
        new NodeTraversal.AbstractShallowCallback() {
          @Override
          public void visit(NodeTraversal t, Node n, Node parent) {
            if (n.isThis()) {
              compiler.report(
                  JSError.make(name.getDeclaration().getSourceName(), n,
                      UNSAFE_THIS, name.getFullName()));
            }
          }
        });
  }
}
 

/**
 * Defines a function literal.
 */
void defineFunctionLiteral(Node n, Node parent) {
  assertDefinitionNode(n, Token.FUNCTION);

  // Determine the name and JSDocInfo and l-value for the function.
  // Any of these may be null.
  Node lValue = NodeUtil.getBestLValue(n);
  JSDocInfo info = NodeUtil.getBestJSDocInfo(n);
  String functionName = NodeUtil.getBestLValueName(lValue);
  FunctionType functionType =
      createFunctionTypeFromNodes(n, functionName, info, lValue);

  // Assigning the function type to the function node
  setDeferredType(n, functionType);

  // Declare this symbol in the current scope iff it's a function
  // declaration. Otherwise, the declaration will happen in other
  // code paths.
  if (NodeUtil.isFunctionDeclaration(n)) {
    defineSlot(n.getFirstChild(), n, functionType);
  }
}
 

/**
 * Gets a function's JSDoc information, if it has any. Checks for a few
 * patterns (ellipses show where JSDoc would be):
 * <pre>
 * ... function() {}
 * ... x = function() {};
 * var ... x = function() {};
 * ... var x = function() {};
 * </pre>
 */
private JSDocInfo getFunctionJsDocInfo(Node n) {
  JSDocInfo jsDoc = n.getJSDocInfo();
  Node parent = n.getParent();
  if (jsDoc == null) {
    int parentType = parent.getType();
    if (parentType == Token.NAME || parentType == Token.ASSIGN) {
      jsDoc = parent.getJSDocInfo();
      if (jsDoc == null && parentType == Token.NAME) {
        Node gramps = parent.getParent();
        if (gramps.getType() == Token.VAR) {
          jsDoc = gramps.getJSDocInfo();
        }
      }
    }
  }
  return jsDoc;
}
 

/**
 * <p>Checks enum aliases.
 *
 * <p>We verify that the enum element type of the enum used
 * for initialization is a subtype of the enum element type of
 * the enum the value is being copied in.</p>
 *
 * <p>Example:</p>
 * <pre>var myEnum = myOtherEnum;</pre>
 *
 * <p>Enum aliases are irregular, so we need special code for this :(</p>
 *
 * @param value the value used for initialization of the enum
 */
private void checkEnumAlias(
    NodeTraversal t, JSDocInfo declInfo, Node value) {
  if (declInfo == null || !declInfo.hasEnumParameterType()) {
    return;
  }

  JSType valueType = getJSType(value);
  if (!valueType.isEnumType()) {
    return;
  }

  EnumType valueEnumType = valueType.toMaybeEnumType();
  JSType valueEnumPrimitiveType =
      valueEnumType.getElementsType().getPrimitiveType();
  validator.expectCanAssignTo(t, value, valueEnumPrimitiveType,
      declInfo.getEnumParameterType().evaluate(t.getScope(), typeRegistry),
      "incompatible enum element types");
}
 

/**
 * Enforces type casts, and ensures the node is typed.
 *
 * A cast in the way that we use it in JSDoc annotations never
 * alters the generated code and therefore never can induce any runtime
 * operation. What this means is that a 'cast' is really just a compile
 * time constraint on the underlying value. In the future, we may add
 * support for run-time casts for compiled tests.
 *
 * To ensure some shred of sanity, we enforce the notion that the
 * type you are casting to may only meaningfully be a narrower type
 * than the underlying declared type. We also invalidate optimizations
 * on bad type casts.
 *
 * @param t The traversal object needed to report errors.
 * @param n The node getting a type assigned to it.
 * @param type The type to be assigned.
 */
private void ensureTyped(NodeTraversal t, Node n, JSType type) {
  // Make sure FUNCTION nodes always get function type.
  Preconditions.checkState(n.getType() != Token.FUNCTION ||
          type instanceof FunctionType ||
          type.isUnknownType());
  JSDocInfo info = n.getJSDocInfo();
  if (info != null) {
    if (info.hasType()) {
      JSType infoType = info.getType().evaluate(t.getScope(), typeRegistry);
      validator.expectCanCast(t, n, infoType, type);
      type = infoType;
    }

    if (info.isImplicitCast() && !inExterns) {
      String propName = n.getType() == Token.GETPROP ?
          n.getLastChild().getString() : "(missing)";
      compiler.report(
          t.makeError(n, ILLEGAL_IMPLICIT_CAST, propName));
    }
  }

  if (n.getJSType() == null) {
    n.setJSType(type);
  }
}
 

@Override
public void setPropertyJSDocInfo(String propertyName, JSDocInfo info) {
  if (info != null) {
    if (!properties.containsKey(propertyName)) {
      // If docInfo was attached, but the type of the property
      // was not defined anywhere, then we consider this an explicit
      // declaration of the property.
      defineInferredProperty(propertyName, getPropertyType(propertyName),
          null);
    }

    // The prototype property is not represented as a normal Property.
    // We probably don't want to attach any JSDoc to it anyway.
    Property property = properties.get(propertyName);
    if (property != null) {
      property.setJSDocInfo(info);
    }
  }
}
 

private void setFileOverviewJsDoc(Node irNode) {
  // Only after we've seen all @fileoverview entries, attach the
  // last one to the root node, and copy the found license strings
  // to that node.
  JSDocInfo rootNodeJsDoc = rootNodeJsDocHolder.getJSDocInfo();
  if (rootNodeJsDoc != null) {
    irNode.setJSDocInfo(rootNodeJsDoc);
    rootNodeJsDoc.setAssociatedNode(irNode);
  }

  if (fileOverviewInfo != null) {
    if ((irNode.getJSDocInfo() != null) &&
        (irNode.getJSDocInfo().getLicense() != null)) {
      fileOverviewInfo.setLicense(irNode.getJSDocInfo().getLicense());
    }
    irNode.setJSDocInfo(fileOverviewInfo);
    fileOverviewInfo.setAssociatedNode(irNode);
  }
}
 

/**
 * <p>Checks enum aliases.
 *
 * <p>We verify that the enum element type of the enum used
 * for initialization is a subtype of the enum element type of
 * the enum the value is being copied in.</p>
 *
 * <p>Example:</p>
 * <pre>var myEnum = myOtherEnum;</pre>
 *
 * <p>Enum aliases are irregular, so we need special code for this :(</p>
 *
 * @param value the value used for initialization of the enum
 */
private void checkEnumAlias(
    NodeTraversal t, JSDocInfo declInfo, Node value) {
  if (declInfo == null || !declInfo.hasEnumParameterType()) {
    return;
  }

  JSType valueType = getJSType(value);
  if (!valueType.isEnumType()) {
    return;
  }

  EnumType valueEnumType = valueType.toMaybeEnumType();
  JSType valueEnumPrimitiveType =
      valueEnumType.getElementsType().getPrimitiveType();
  validator.expectCanAssignTo(t, value, valueEnumPrimitiveType,
      declInfo.getEnumParameterType().evaluate(t.getScope(), typeRegistry),
      "incompatible enum element types");
}
 

/**
 * Gets a function's JSDoc information, if it has any. Checks for a few
 * patterns (ellipses show where JSDoc would be):
 * <pre>
 * ... function() {}
 * ... x = function() {};
 * var ... x = function() {};
 * ... var x = function() {};
 * </pre>
 */
private JSDocInfo getFunctionJsDocInfo(Node n) {
  JSDocInfo jsDoc = n.getJSDocInfo();
  Node parent = n.getParent();
  if (jsDoc == null) {
    int parentType = parent.getType();
    if (parentType == Token.NAME || parentType == Token.ASSIGN) {
      jsDoc = parent.getJSDocInfo();
      if (jsDoc == null && parentType == Token.NAME) {
        Node gramps = parent.getParent();
        if (gramps.getType() == Token.VAR) {
          jsDoc = gramps.getJSDocInfo();
        }
      }
    }
  }
  return jsDoc;
}
 

private void setFileOverviewJsDoc(Node irNode) {
  // Only after we've seen all @fileoverview entries, attach the
  // last one to the root node, and copy the found license strings
  // to that node.
  JSDocInfo rootNodeJsDoc = rootNodeJsDocHolder.getJSDocInfo();
  if (rootNodeJsDoc != null) {
    irNode.setJSDocInfo(rootNodeJsDoc);
    rootNodeJsDoc.setAssociatedNode(irNode);
  }

  if (fileOverviewInfo != null) {
    if ((irNode.getJSDocInfo() != null) &&
        (irNode.getJSDocInfo().getLicense() != null)) {
      fileOverviewInfo.setLicense(irNode.getJSDocInfo().getLicense());
    }
    irNode.setJSDocInfo(fileOverviewInfo);
    fileOverviewInfo.setAssociatedNode(irNode);
  }
}
 

private void checkNoTypeCheckSection(Node n, boolean enterSection) {
  switch (n.getType()) {
    case Token.SCRIPT:
    case Token.BLOCK:
    case Token.VAR:
    case Token.FUNCTION:
    case Token.ASSIGN:
      JSDocInfo info = n.getJSDocInfo();
      if (info != null && info.isNoTypeCheck()) {
        if (enterSection) {
          noTypeCheckSection++;
        } else {
          noTypeCheckSection--;
        }
      }
      validator.setShouldReport(noTypeCheckSection == 0);
      break;
  }
}
 

@Override
public JSDocInfo getOwnPropertyJSDocInfo(String propertyName) {
  Property p = properties.get(propertyName);
  if (p != null) {
    return p.getJSDocInfo();
  }
  return null;
}
 

/**
 * @return Whether the given param is an optional param.
 */
private boolean isOptionalParameter(
    Node param, @Nullable JSDocInfo info) {
  if (codingConvention.isOptionalParameter(param)) {
    return true;
  }

  String paramName = param.getString();
  return info != null && info.hasParameterType(paramName) &&
      info.getParameterType(paramName).isOptionalArg();
}
 

public void testTypedefType3() throws Exception {
  JSDocInfo info = parse("@typedef \n {(string|number)}*/");
  assertTrue(info.hasTypedefType());
  assertTypeEquals(
      createUnionType(NUMBER_TYPE, STRING_TYPE),
      info.getTypedefType());
}
 

/**
 * @returns Whether the @modifies annotation includes "arguments"
 * or any named parameters.
 */
private boolean hasSideEffectsArgumentsAnnotation(JSDocInfo docInfo) {
  Preconditions.checkNotNull(docInfo);
  Set<String> modifies = docInfo.getModifies();
  // TODO(johnlenz): if we start tracking parameters individually
  // this should simply be a check for "arguments".
  return (modifies.size() > 1
      || (modifies.size() == 1 && !modifies.contains("this")));
}
 

/**
 * Process an object literal and all the types on it.
 * @param objLit The OBJECTLIT node.
 * @param objLitType The type of the OBJECTLIT node. This might be a named
 *     type, because of the lends annotation.
 * @param declareOnOwner If true, declare properties on the objLitType as
 *     well. If false, the caller should take crae of this.
 */
void processObjectLitProperties(
    Node objLit, ObjectType objLitType,
    boolean declareOnOwner) {
  for (Node keyNode = objLit.getFirstChild(); keyNode != null;
       keyNode = keyNode.getNext()) {
    Node value = keyNode.getFirstChild();
    String memberName = NodeUtil.getObjectLitKeyName(keyNode);
    JSDocInfo info = keyNode.getJSDocInfo();
    JSType valueType =
        getDeclaredType(keyNode.getSourceFileName(), info, keyNode, value);
    JSType keyType =  objLitType.isEnumType() ?
        objLitType.toMaybeEnumType().getElementsType() :
        NodeUtil.getObjectLitKeyTypeFromValueType(keyNode, valueType);

    // Try to declare this property in the current scope if it
    // has an authoritative name.
    String qualifiedName = NodeUtil.getBestLValueName(keyNode);
    if (qualifiedName != null) {
      boolean inferred = keyType == null;
      defineSlot(keyNode, objLit, qualifiedName, keyType, inferred);
    } else if (keyType != null) {
      setDeferredType(keyNode, keyType);
    }

    if (keyType != null && objLitType != null && declareOnOwner) {
      // Declare this property on its object literal.
      boolean isExtern = keyNode.isFromExterns();
      objLitType.defineDeclaredProperty(memberName, keyType, keyNode);
    }
  }
}
 

private Node transformNumberAsString(NumberLiteral literalNode) {
  Node irNode = newStringNode(getStringValue(literalNode.getNumber()));
  JSDocInfo jsDocInfo = handleJsDoc(literalNode, irNode);
  if (jsDocInfo != null) {
    irNode.setJSDocInfo(jsDocInfo);
  }
  setSourceInfo(irNode, literalNode);
  return irNode;
}
 

/**
 * Infer the return type from JSDocInfo.
 */
FunctionTypeBuilder inferReturnType(@Nullable JSDocInfo info) {
  if (info != null && info.hasReturnType()) {
    returnType = info.getReturnType().evaluate(scope, typeRegistry);
    returnTypeInferred = false;
  }

  if (templateTypeName != null &&
      returnType != null &&
      returnType.restrictByNotNullOrUndefined().isTemplateType()) {
    reportError(TEMPLATE_TYPE_EXPECTED, fnName);
  }
  return this;
}
 

/**
 * Infers the type of {@code this}.
 * @param type The type of this if the info is missing.
 */
FunctionTypeBuilder inferThisType(JSDocInfo info, JSType type) {
  // Look at the @this annotation first.
  inferThisType(info);

  if (thisType == null) {
    ObjectType objType = ObjectType.cast(type);
    if (objType != null && (info == null || !info.hasType())) {
      thisType = objType;
    }
  }

  return this;
}