+++ /dev/null
-/*******************************************************************************
- * 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.lookup.*;
-
-/**
- * Node representing a structured Javadoc comment
- */
-public class Javadoc extends ASTNode {
-
- public JavadocSingleNameReference[] parameters; // @param
- public TypeReference[] thrownExceptions; // @throws, @exception
- public JavadocReturnStatement returnStatement; // @return
- public Expression[] references; // @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.parameters != null) {
- for (int i = 0, length = this.parameters.length; i < length; i++) {
- printIndent(indent + 1, output).append(" * @param "); //$NON-NLS-1$
- this.parameters[i].print(indent, output).append('\n');
- }
- }
- if (this.returnStatement != null) {
- printIndent(indent + 1, output).append(" * @return\n"); //$NON-NLS-1$
- }
- if (this.thrownExceptions != null) {
- for (int i = 0, length = this.thrownExceptions.length; i < length; i++) {
- printIndent(indent + 1, output).append(" * @throws "); //$NON-NLS-1$
- this.thrownExceptions[i].print(indent, output).append('\n');
- }
- }
- if (this.references != null) {
- for (int i = 0, length = this.references.length; i < length; i++) {
- printIndent(indent + 1, output).append(" * @see"); //$NON-NLS-1$
- this.references[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.parameters == null ? 0 : this.parameters.length;
- for (int i = 0; i < paramTagsSize; i++) {
- JavadocSingleNameReference param = this.parameters[i];
- classScope.problemReporter().javadocUnexpectedTag(param.tagSourceStart, param.tagSourceEnd);
- }
-
- // @return tags
- if (this.returnStatement != null) {
- classScope.problemReporter().javadocUnexpectedTag(this.returnStatement.sourceStart, this.returnStatement.sourceEnd);
- }
-
- // @throws/@exception tags
- int throwsTagsLength = this.thrownExceptions == null ? 0 : this.thrownExceptions.length;
- for (int i = 0; i < throwsTagsLength; i++) {
- TypeReference typeRef = this.thrownExceptions[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.references == null ? 0 : this.references.length;
- for (int i = 0; i < seeTagsLength; i++) {
-
- // Resolve reference
- this.references[i].resolveType(classScope);
-
- // Some unbound field reference might be changed to message send
- // see bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=51911
- if (this.references[i] instanceof JavadocFieldReference) {
- JavadocFieldReference fieldRef = (JavadocFieldReference) this.references[i];
- if (fieldRef.receiverType != null && fieldRef.binding == null) { // binding was reset in case of valid method reference
- // TODO (frederic) post 3.0 - avoid new instanciation of Compiler AST node
- JavadocMessageSend msgSend = new JavadocMessageSend(fieldRef.token, fieldRef.nameSourcePosition);
- msgSend.receiver = fieldRef.receiver;
- msgSend.receiverType = fieldRef.receiverType;
- msgSend.qualifyingType = fieldRef.receiverType;
- msgSend.superAccess = classScope.enclosingSourceType().isCompatibleWith(msgSend.receiverType);
- msgSend.binding = classScope.findMethod((ReferenceBinding)msgSend.receiverType, msgSend.selector, new TypeBinding[0], msgSend);
- this.references[i] = msgSend;
- }
- }
- }
- }
-
- /*
- * 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.references == null ? 0 : this.references.length;
- boolean superRef = false;
- for (int i = 0; i < seeTagsLength; i++) {
-
- // Resolve reference
- this.references[i].resolveType(methScope);
-
- // Some unbound field reference might be changed to message send
- // see bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=51911
- if (this.references[i] instanceof JavadocFieldReference) {
- JavadocFieldReference fieldRef = (JavadocFieldReference) this.references[i];
- if (fieldRef.receiverType != null && fieldRef.binding == null) { // binding was reset in case of valid method reference
- // TODO (frederic) post 3.0 - avoid new instanciation of Compiler AST node
- JavadocMessageSend msgSend = new JavadocMessageSend(fieldRef.token, fieldRef.nameSourcePosition);
- msgSend.receiver = fieldRef.receiver;
- msgSend.receiverType = fieldRef.receiverType;
- msgSend.qualifyingType = fieldRef.receiverType;
- msgSend.superAccess = methScope.enclosingSourceType().isCompatibleWith(msgSend.receiverType);
- msgSend.binding = methScope.findMethod((ReferenceBinding)msgSend.receiverType, msgSend.selector, new TypeBinding[0], msgSend);
- this.references[i] = msgSend;
- }
- }
-
- // see whether we can have a super reference
- try {
- if (methDecl != null && (methDecl.isConstructor() || overriding) && !superRef) {
- if (this.references[i] instanceof JavadocMessageSend) {
- JavadocMessageSend messageSend = (JavadocMessageSend) this.references[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.receiverType) &&
- 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.references[i] instanceof JavadocAllocationExpression) {
- JavadocAllocationExpression allocationExpr = (JavadocAllocationExpression) this.references[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);
-
- // @return tags
- if (this.returnStatement == null) {
- if (reportMissing && methDecl != null) {
- if (!methDecl.isConstructor() && !methDecl.isClinit()) {
- 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);
- }
- }
-
- /*
- * Resolve @param tags while method scope
- */
- private void resolveParamTags(MethodScope methScope, boolean reportMissing) {
- AbstractMethodDeclaration md = methScope.referenceMethod();
- int paramTagsSize = this.parameters == null ? 0 : this.parameters.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.parameters[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, 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.parameters[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, 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, md.binding.modifiers);
- }
- }
- }
- }
- }
-
- /*
- * Resolve @throws/@exception tags while method scope
- */
- private void resolveThrowsTags(MethodScope methScope, boolean reportMissing) {
- AbstractMethodDeclaration md = methScope.referenceMethod();
- int throwsTagsLength = this.thrownExceptions == null ? 0 : this.thrownExceptions.length;
-
- // If no referenced method (field initializer for example) then report a problem for each throws tag
- if (md == null) {
- for (int i = 0; i < throwsTagsLength; i++) {
- TypeReference typeRef = this.thrownExceptions[i];
- int start = typeRef.sourceStart;
- int end = typeRef.sourceEnd;
- if (typeRef instanceof JavadocQualifiedTypeReference) {
- start = ((JavadocQualifiedTypeReference) typeRef).tagSourceStart;
- end = ((JavadocQualifiedTypeReference) typeRef).tagSourceEnd;
- } else if (typeRef instanceof JavadocSingleTypeReference) {
- start = ((JavadocSingleTypeReference) typeRef).tagSourceStart;
- end = ((JavadocSingleTypeReference) typeRef).tagSourceEnd;
- }
- methScope.problemReporter().javadocUnexpectedTag(start, end);
- }
- return;
- }
-
- // If no throws tags then report a problem for each method thrown exception
- int boundExceptionLength = (md.binding == null || md.binding.thrownExceptions == null) ? 0 : md.binding.thrownExceptions.length;
- int thrownExceptionLength = md.thrownExceptions == null ? 0 : md.thrownExceptions.length;
- if (throwsTagsLength == 0) {
- if (reportMissing) {
- for (int i = 0; i < boundExceptionLength; i++) {
- ReferenceBinding exceptionBinding = md.binding.thrownExceptions[i];
- if (exceptionBinding != null && exceptionBinding.isValidBinding()) { // flag only valid class name
- int j=i;
- while (j<thrownExceptionLength && exceptionBinding != md.thrownExceptions[j].resolvedType) j++;
- if (j<thrownExceptionLength) {
- methScope.problemReporter().javadocMissingThrowsTag(md.thrownExceptions[j], md.binding.modifiers);
- }
- }
- }
- }
- } else {
- int maxRef = 0;
- TypeReference[] typeReferences = new TypeReference[throwsTagsLength];
-
- // Scan all @throws tags
- for (int i = 0; i < throwsTagsLength; i++) {
- TypeReference typeRef = this.thrownExceptions[i];
- typeRef.resolve(methScope);
- TypeBinding typeBinding = typeRef.resolvedType;
-
- if (typeBinding != null && typeBinding.isValidBinding() && typeBinding.isClass()) {
- typeReferences[maxRef++] = typeRef;
- }
- }
-
- // Look for undocumented thrown exception
- for (int i = 0; i < boundExceptionLength; i++) {
- ReferenceBinding exceptionBinding = md.binding.thrownExceptions[i];
- boolean found = false;
- for (int j = 0; j < maxRef && !found; j++) {
- if (typeReferences[j] != null) {
- TypeBinding typeBinding = typeReferences[j].resolvedType;
- if (exceptionBinding == typeBinding) {
- found = true;
- typeReferences[j] = null;
- }
- }
- }
- if (!found && reportMissing) {
- if (exceptionBinding != null && exceptionBinding.isValidBinding()) { // flag only valid class name
- int k=i;
- while (k<thrownExceptionLength && exceptionBinding != md.thrownExceptions[k].resolvedType) k++;
- if (k<thrownExceptionLength) {
- methScope.problemReporter().javadocMissingThrowsTag(md.thrownExceptions[k], md.binding.modifiers);
- }
- }
- }
- }
-
- // Verify additional @throws tags
- for (int i = 0; i < maxRef; i++) {
- TypeReference typeRef = typeReferences[i];
- if (typeRef != null) {
- boolean compatible = false;
- // thrown exceptions subclasses are accepted
- for (int j = 0; j<thrownExceptionLength && !compatible; j++) {
- TypeBinding exceptionBinding = md.thrownExceptions[j].resolvedType;
- if (exceptionBinding != null) {
- compatible = typeRef.resolvedType.isCompatibleWith(exceptionBinding);
- }
- }
-
- // If not compatible only complain on unchecked exception
- if (!compatible &&
- !typeRef.resolvedType.isCompatibleWith(methScope.getJavaLangRuntimeException()) &&
- !typeRef.resolvedType.isCompatibleWith(methScope.getJavaLangError())) {
- methScope.problemReporter().javadocInvalidThrowsClassName(typeRef, md.binding.modifiers);
- }
- }
- }
- }
- }
-
- /*
- * Search node with a given staring position in javadoc objects arrays.
- */
- public ASTNode getNodeStartingAt(int start) {
- // parameters array
- if (this.parameters != null) {
- for (int i=0; i<this.parameters.length; i++) {
- JavadocSingleNameReference param = this.parameters[i];
- if (param.sourceStart==start) {
- return param;
- }
- }
- }
- // array of invalid syntax tags parameters
- if (this.invalidParameters != null) {
- for (int i=0; i<this.invalidParameters.length; i++) {
- JavadocSingleNameReference param = this.invalidParameters[i];
- if (param.sourceStart==start) {
- return param;
- }
- }
- }
- // thrown exception array
- if (this.thrownExceptions != null) {
- for (int i=0; i<this.thrownExceptions.length; i++) {
- TypeReference typeRef = this.thrownExceptions[i];
- if (typeRef.sourceStart==start) {
- return typeRef;
- }
- }
- }
- // references array
- if (this.references != null) {
- for (int i=0; i<this.references.length; i++) {
- org.eclipse.jdt.internal.compiler.ast.Expression expression = this.references[i];
- if (expression.sourceStart==start) {
- return expression;
- } else if (expression instanceof JavadocAllocationExpression) {
- JavadocAllocationExpression allocationExpr = (JavadocAllocationExpression) this.references[i];
- // if binding is valid then look at arguments
- if (allocationExpr.binding != null && allocationExpr.binding.isValidBinding()) {
- if (allocationExpr.arguments != null) {
- for (int j=0; j<allocationExpr.arguments.length; j++) {
- if (allocationExpr.arguments[j].sourceStart == start) {
- return allocationExpr.arguments[j];
- }
- }
- }
- }
- } else if (expression instanceof JavadocMessageSend) {
- JavadocMessageSend messageSend = (JavadocMessageSend) this.references[i];
- // if binding is valid then look at arguments
- if (messageSend.binding != null && messageSend.binding.isValidBinding()) {
- if (messageSend.arguments != null) {
- for (int j=0; j<messageSend.arguments.length; j++) {
- if (messageSend.arguments[j].sourceStart == start) {
- return messageSend.arguments[j];
- }
- }
- }
- }
- }
- }
- }
- return null;
- }
-}
projects / org.ibex.tool.git / blobdiff