/******************************************************************************* * Copyright (c) 2000, 2004 IBM Corporation and others. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Common Public License v1.0 * which accompanies this distribution, and is available at * http://www.eclipse.org/legal/cpl-v10.html * * Contributors: * IBM Corporation - initial API and implementation *******************************************************************************/ package org.eclipse.jdt.internal.compiler.ast; import org.eclipse.jdt.core.compiler.CharOperation; import org.eclipse.jdt.internal.compiler.classfmt.ClassFileConstants; import org.eclipse.jdt.internal.compiler.lookup.*; import org.eclipse.jdt.internal.compiler.parser.AbstractCommentParser; /** * Node representing a structured Javadoc comment */ public class Javadoc extends ASTNode { public JavadocSingleNameReference[] paramReferences; // @param public JavadocSingleTypeReference[] paramTypeParameters; // @param public TypeReference[] exceptionReferences; // @throws, @exception public JavadocReturnStatement returnStatement; // @return public Expression[] seeReferences; // @see public boolean inherited = false; // bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=51600 // Store param references for tag with invalid syntax public JavadocSingleNameReference[] invalidParameters; // @param public Javadoc(int sourceStart, int sourceEnd) { this.sourceStart = sourceStart; this.sourceEnd = sourceEnd; } /* * @see org.eclipse.jdt.internal.compiler.ast.ASTNode#print(int, java.lang.StringBuffer) */ public StringBuffer print(int indent, StringBuffer output) { printIndent(indent, output).append("/**\n"); //$NON-NLS-1$ if (this.paramReferences != null) { for (int i = 0, length = this.paramReferences.length; i < length; i++) { printIndent(indent + 1, output).append(" * @param "); //$NON-NLS-1$ this.paramReferences[i].print(indent, output).append('\n'); } } if (this.paramTypeParameters != null) { for (int i = 0, length = this.paramTypeParameters.length; i < length; i++) { printIndent(indent + 1, output).append(" * @param <"); //$NON-NLS-1$ this.paramTypeParameters[i].print(indent, output).append(">\n"); //$NON-NLS-1$ } } if (this.returnStatement != null) { printIndent(indent + 1, output).append(" * @"); //$NON-NLS-1$ this.returnStatement.print(indent, output).append('\n'); } if (this.exceptionReferences != null) { for (int i = 0, length = this.exceptionReferences.length; i < length; i++) { printIndent(indent + 1, output).append(" * @throws "); //$NON-NLS-1$ this.exceptionReferences[i].print(indent, output).append('\n'); } } if (this.seeReferences != null) { for (int i = 0, length = this.seeReferences.length; i < length; i++) { printIndent(indent + 1, output).append(" * @see"); //$NON-NLS-1$ this.seeReferences[i].print(indent, output).append('\n'); } } printIndent(indent, output).append(" */\n"); //$NON-NLS-1$ return output; } /* * Resolve type javadoc while a class scope */ public void resolve(ClassScope classScope) { // @param tags int paramTagsSize = this.paramReferences == null ? 0 : this.paramReferences.length; for (int i = 0; i < paramTagsSize; i++) { JavadocSingleNameReference param = this.paramReferences[i]; classScope.problemReporter().javadocUnexpectedTag(param.tagSourceStart, param.tagSourceEnd); } resolveTypeParameterTags(classScope, true); // @return tags if (this.returnStatement != null) { classScope.problemReporter().javadocUnexpectedTag(this.returnStatement.sourceStart, this.returnStatement.sourceEnd); } // @throws/@exception tags int throwsTagsLength = this.exceptionReferences == null ? 0 : this.exceptionReferences.length; for (int i = 0; i < throwsTagsLength; i++) { TypeReference typeRef = this.exceptionReferences[i]; int start, end; if (typeRef instanceof JavadocSingleTypeReference) { JavadocSingleTypeReference singleRef = (JavadocSingleTypeReference) typeRef; start = singleRef.tagSourceStart; end = singleRef.tagSourceEnd; } else if (typeRef instanceof JavadocQualifiedTypeReference) { JavadocQualifiedTypeReference qualifiedRef = (JavadocQualifiedTypeReference) typeRef; start = qualifiedRef.tagSourceStart; end = qualifiedRef.tagSourceEnd; } else { start = typeRef.sourceStart; end = typeRef.sourceEnd; } classScope.problemReporter().javadocUnexpectedTag(start, end); } // @see tags int seeTagsLength = this.seeReferences == null ? 0 : this.seeReferences.length; for (int i = 0; i < seeTagsLength; i++) { resolveReference(this.seeReferences[i], classScope); } } /* * Resolve method javadoc while a method scope */ public void resolve(MethodScope methScope) { // get method declaration AbstractMethodDeclaration methDecl = methScope.referenceMethod(); boolean overriding = methDecl == null ? false : (methDecl.binding.modifiers & (AccImplementing | AccOverriding)) != 0; // @see tags int seeTagsLength = this.seeReferences == null ? 0 : this.seeReferences.length; boolean superRef = false; for (int i = 0; i < seeTagsLength; i++) { // Resolve reference resolveReference(this.seeReferences[i], methScope); // see whether we can have a super reference try { if (methDecl != null && (methDecl.isConstructor() || overriding) && !superRef) { if (this.seeReferences[i] instanceof JavadocMessageSend) { JavadocMessageSend messageSend = (JavadocMessageSend) this.seeReferences[i]; // if binding is valid then look if we have a reference to an overriden method/constructor if (messageSend.binding != null && messageSend.binding.isValidBinding()) { if (methDecl.binding.declaringClass.isCompatibleWith(messageSend.actualReceiverType) && CharOperation.equals(messageSend.selector, methDecl.selector) && (messageSend.binding.returnType == methDecl.binding.returnType)) { if (messageSend.arguments == null && methDecl.arguments == null) { superRef = true; } else if (messageSend.arguments != null && methDecl.arguments != null) { superRef = methDecl.binding.areParametersEqual(messageSend.binding); } } } } else if (this.seeReferences[i] instanceof JavadocAllocationExpression) { JavadocAllocationExpression allocationExpr = (JavadocAllocationExpression) this.seeReferences[i]; // if binding is valid then look if we have a reference to an overriden method/constructor if (allocationExpr.binding != null && allocationExpr.binding.isValidBinding()) { if (methDecl.binding.declaringClass.isCompatibleWith(allocationExpr.resolvedType)) { if (allocationExpr.arguments == null && methDecl.arguments == null) { superRef = true; } else if (allocationExpr.arguments != null && methDecl.arguments != null) { superRef = methDecl.binding.areParametersEqual(allocationExpr.binding); } } } } } } catch (Exception e) { // Something wrong happen, forget super ref... } } // Store if a reference exists to an overriden method/constructor or the method is in a local type, boolean reportMissing = methDecl == null || !((overriding && this.inherited) || superRef || (methDecl.binding.declaringClass != null && methDecl.binding.declaringClass.isLocalType())); // @param tags resolveParamTags(methScope, reportMissing); resolveTypeParameterTags(methScope, reportMissing); // @return tags if (this.returnStatement == null) { if (reportMissing && methDecl != null) { if (methDecl.isMethod()) { MethodDeclaration meth = (MethodDeclaration) methDecl; if (meth.binding.returnType != VoidBinding) { // method with return should have @return tag methScope.problemReporter().javadocMissingReturnTag(meth.returnType.sourceStart, meth.returnType.sourceEnd, methDecl.binding.modifiers); } } } } else { this.returnStatement.resolve(methScope); } // @throws/@exception tags resolveThrowsTags(methScope, reportMissing); // Resolve param tags with invalid syntax int length = this.invalidParameters == null ? 0 : this.invalidParameters.length; for (int i = 0; i < length; i++) { this.invalidParameters[i].resolve(methScope, false); } } private void resolveReference(Expression reference, Scope scope) { // Perform resolve switch (scope.kind) { case Scope.METHOD_SCOPE: reference.resolveType((MethodScope)scope); break; case Scope.CLASS_SCOPE: reference.resolveType((ClassScope)scope); break; } // Verify field references boolean verifyValues = scope.environment().options.sourceLevel >= ClassFileConstants.JDK1_5; if (reference instanceof JavadocFieldReference) { JavadocFieldReference fieldRef = (JavadocFieldReference) reference; int modifiers = fieldRef.binding==null ? -1 : fieldRef.binding.modifiers; // Verify if this is a method reference // see bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=51911 if (fieldRef.methodBinding != null) { // cannot refer to method for @value tag if (fieldRef.tagValue == AbstractCommentParser.TAG_VALUE_VALUE) { scope.problemReporter().javadocInvalidValueReference(fieldRef.sourceStart, fieldRef.sourceEnd, modifiers); } else if (fieldRef.receiverType != null) { fieldRef.superAccess = scope.enclosingSourceType().isCompatibleWith(fieldRef.receiverType); fieldRef.methodBinding = scope.findMethod((ReferenceBinding)fieldRef.receiverType, fieldRef.token, new TypeBinding[0], fieldRef); } } // Verify whether field ref should be static or not (for @value tags) else if (verifyValues && fieldRef.binding != null && fieldRef.binding.isValidBinding()) { if (fieldRef.tagValue == AbstractCommentParser.TAG_VALUE_VALUE && !fieldRef.binding.isStatic()) { scope.problemReporter().javadocInvalidValueReference(fieldRef.sourceStart, fieldRef.sourceEnd, modifiers); } } } // If not 1.5 level, verification is finished if (!verifyValues) return; // Verify that message reference are not used for @value tags else if (reference instanceof JavadocMessageSend) { JavadocMessageSend msgSend = (JavadocMessageSend) reference; int modifiers = msgSend.binding==null ? -1 : msgSend.binding.modifiers; if (msgSend.tagValue == AbstractCommentParser.TAG_VALUE_VALUE) { // cannot refer to method for @value tag scope.problemReporter().javadocInvalidValueReference(msgSend.sourceStart, msgSend.sourceEnd, modifiers); } } // Verify that constructorreference are not used for @value tags else if (reference instanceof JavadocAllocationExpression) { JavadocAllocationExpression alloc = (JavadocAllocationExpression) reference; int modifiers = alloc.binding==null ? -1 : alloc.binding.modifiers; if (alloc.tagValue == AbstractCommentParser.TAG_VALUE_VALUE) { // cannot refer to method for @value tag scope.problemReporter().javadocInvalidValueReference(alloc.sourceStart, alloc.sourceEnd, modifiers); } } } /* * Resolve @param tags while method scope */ private void resolveParamTags(MethodScope methScope, boolean reportMissing) { AbstractMethodDeclaration md = methScope.referenceMethod(); int paramTagsSize = this.paramReferences == null ? 0 : this.paramReferences.length; // If no referenced method (field initializer for example) then report a problem for each param tag if (md == null) { for (int i = 0; i < paramTagsSize; i++) { JavadocSingleNameReference param = this.paramReferences[i]; methScope.problemReporter().javadocUnexpectedTag(param.tagSourceStart, param.tagSourceEnd); } return; } // If no param tags then report a problem for each method argument int argumentsSize = md.arguments == null ? 0 : md.arguments.length; if (paramTagsSize == 0) { if (reportMissing) { for (int i = 0; i < argumentsSize; i++) { Argument arg = md.arguments[i]; methScope.problemReporter().javadocMissingParamTag(arg.name, arg.sourceStart, arg.sourceEnd, md.binding.modifiers); } } } else { LocalVariableBinding[] bindings = new LocalVariableBinding[paramTagsSize]; int maxBindings = 0; // Scan all @param tags for (int i = 0; i < paramTagsSize; i++) { JavadocSingleNameReference param = this.paramReferences[i]; param.resolve(methScope); if (param.binding != null && param.binding.isValidBinding()) { // Verify duplicated tags boolean found = false; for (int j = 0; j < maxBindings && !found; j++) { if (bindings[j] == param.binding) { methScope.problemReporter().javadocDuplicatedParamTag(param.token, param.sourceStart, param.sourceEnd, md.binding.modifiers); found = true; } } if (!found) { bindings[maxBindings++] = (LocalVariableBinding) param.binding; } } } // Look for undocumented arguments if (reportMissing) { for (int i = 0; i < argumentsSize; i++) { Argument arg = md.arguments[i]; boolean found = false; for (int j = 0; j < maxBindings && !found; j++) { LocalVariableBinding binding = bindings[j]; if (arg.binding == binding) { found = true; } } if (!found) { methScope.problemReporter().javadocMissingParamTag(arg.name, arg.sourceStart, arg.sourceEnd, md.binding.modifiers); } } } } } /* * Resolve @param tags for type parameters */ private void resolveTypeParameterTags(Scope scope, boolean reportMissing) { int paramTypeParamLength = this.paramTypeParameters == null ? 0 : this.paramTypeParameters.length; // Get declaration infos TypeDeclaration typeDeclaration = null; AbstractMethodDeclaration methodDeclaration = null; TypeVariableBinding[] typeVariables = null; int modifiers = -1; switch (scope.kind) { case Scope.METHOD_SCOPE: methodDeclaration = ((MethodScope)scope).referenceMethod(); // If no referenced method (field initializer for example) then report a problem for each param tag if (methodDeclaration == null) { for (int i = 0; i < paramTypeParamLength; i++) { JavadocSingleNameReference param = this.paramReferences[i]; scope.problemReporter().javadocUnexpectedTag(param.tagSourceStart, param.tagSourceEnd); } return; } typeVariables = methodDeclaration.binding.typeVariables; modifiers = methodDeclaration.binding.modifiers; break; case Scope.CLASS_SCOPE: typeDeclaration = ((ClassScope) scope).referenceContext; typeVariables = typeDeclaration.binding.typeVariables; modifiers = typeDeclaration.binding.modifiers; break; } // If no type variables then report a problem for each param type parameter tag if (typeVariables == null || typeVariables.length == 0) { for (int i = 0; i < paramTypeParamLength; i++) { JavadocSingleTypeReference param = this.paramTypeParameters[i]; scope.problemReporter().javadocUnexpectedTag(param.tagSourceStart, param.tagSourceEnd); } return; } // If no param tags then report a problem for each declaration type parameter TypeParameter[] parameters = typeDeclaration==null ? methodDeclaration.typeParameters() : typeDeclaration.typeParameters; int typeParametersLength = parameters == null ? 0 : parameters.length; if (paramTypeParamLength == 0) { if (reportMissing) { for (int i = 0, l=parameters.length; i