All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.eclipse.jdt.internal.compiler.ast.Javadoc Maven / Gradle / Ivy

Go to download 

/*******************************************************************************
 * Copyright (c) 2000, 2020 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *     Stephan Herrmann - Contribution for
 *								Bug 400874 - [1.8][compiler] Inference infrastructure should evolve to meet JLS8 18.x (Part G of JSR335 spec)
 *								Bug 429958 - [1.8][null] evaluate new DefaultLocation attribute of @NonNullByDefault
 *******************************************************************************/
package org.eclipse.jdt.internal.compiler.ast;

import org.eclipse.jdt.core.compiler.CharOperation;
import org.eclipse.jdt.internal.compiler.ASTVisitor;
import org.eclipse.jdt.internal.compiler.classfmt.ClassFileConstants;
import org.eclipse.jdt.internal.compiler.impl.CompilerOptions;
import org.eclipse.jdt.internal.compiler.lookup.*;
import org.eclipse.jdt.internal.compiler.parser.JavadocTagConstants;

/**
 * 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 IJavadocTypeReference[] usesReferences; // @uses
	public IJavadocTypeReference[] providesReferences; // @provides
	public long[] inheritedPositions = null;
	// bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=51600
	// Store param references for tag with invalid syntax
	public JavadocSingleNameReference[] invalidParameters; // @param
	// bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=153399
	// Store value tag positions
	public long valuePositions = -1;

	public Javadoc(int sourceStart, int sourceEnd) {
		this.sourceStart = sourceStart;
		this.sourceEnd = sourceEnd;
		this.bits |= ASTNode.ResolveJavadoc;
	}
	/**
	 * Returns whether a type can be seen at a given visibility level or not.
	 *
	 * @param visibility Level of visiblity allowed to see references
	 * @param modifiers modifiers of java element to be seen
	 * @return true if the type can be seen, false otherwise
	 */
	boolean canBeSeen(int visibility, int modifiers) {
		if (modifiers < 0) return true;
		switch (modifiers & ExtraCompilerModifiers.AccVisibilityMASK) {
			case ClassFileConstants.AccPublic :
				return true;
			case ClassFileConstants.AccProtected:
				return (visibility != ClassFileConstants.AccPublic);
			case ClassFileConstants.AccDefault:
				return (visibility == ClassFileConstants.AccDefault || visibility == ClassFileConstants.AccPrivate);
			case ClassFileConstants.AccPrivate:
				return (visibility == ClassFileConstants.AccPrivate);
		}
		return true;
	}

	/*
	 * Search node with a given staring position in javadoc objects arrays.
	 */
	public ASTNode getNodeStartingAt(int start) {
		int length = 0;
		// parameters array
		if (this.paramReferences != null) {
			length = this.paramReferences.length;
			for (int i=0; i\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 (TypeReference reference : this.exceptionReferences) {
				printIndent(indent + 1, output).append(" * @throws "); //$NON-NLS-1$
				reference.print(indent, output).append('\n');
			}
		}
		if (this.seeReferences != null) {
			for (Expression reference : this.seeReferences) {
				printIndent(indent + 1, output).append(" * @see "); //$NON-NLS-1$
				reference.print(indent, output).append('\n');
			}
		}
		printIndent(indent, output).append(" */\n"); //$NON-NLS-1$
		return output;
	}

	/*
	 * Resolve type javadoc
	 */
	public void resolve(ClassScope scope) {
		if ((this.bits & ASTNode.ResolveJavadoc) == 0) {
			return;
		}

		this.bits &= ~ASTNode.ResolveJavadoc;// avoid double resolution

		// https://bugs.eclipse.org/bugs/show_bug.cgi?id=247037, @inheritDoc tag cannot
		// be used in the documentation comment for a class or interface.
		if (this.inheritedPositions != null) {
			int length = this.inheritedPositions.length;
			for (int i = 0; i < length; ++i) {
				int start = (int) (this.inheritedPositions[i] >>> 32);
				int end = (int) this.inheritedPositions[i];
				scope.problemReporter().javadocUnexpectedTag(start, end);
			}
		}
		// @param tags
		int paramTagsSize = this.paramReferences == null ? 0 : this.paramReferences.length;
		for (int i = 0; i < paramTagsSize; i++) {
			if(scope.referenceContext.nRecordComponents > 0) {
				break;
			}
			JavadocSingleNameReference param = this.paramReferences[i];
			scope.problemReporter().javadocUnexpectedTag(param.tagSourceStart, param.tagSourceEnd);
		}
		resolveTypeParameterTags(scope, true);

		// @return tags
		if (this.returnStatement != null) {
			scope.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;
			}
			scope.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], scope);
		}

		// @value tag
		boolean source15 = scope.compilerOptions().sourceLevel >= ClassFileConstants.JDK1_5;
		if (!source15 && this.valuePositions != -1) {
			scope.problemReporter().javadocUnexpectedTag((int)(this.valuePositions>>>32), (int) this.valuePositions);
		}
	}

	/*
	 * Resolve compilation unit javadoc
	 */
	public void resolve(CompilationUnitScope unitScope) {
		if ((this.bits & ASTNode.ResolveJavadoc) == 0) {
			return;
		}
		// Do nothing - This is to mimic the SDK's javadoc tool behavior, which neither
		// sanity checks nor generates documentation using comments at the CU scope
		// (unless the unit happens to be package-info.java - in which case we don't come here.)
	}

	/*
	 * Resolve module info javadoc
	 */
	public void resolve(ModuleScope moduleScope) {
		if ((this.bits & ASTNode.ResolveJavadoc) == 0) {
			return;
		}

		this.bits &= ~ASTNode.ResolveJavadoc;// avoid double resolution

		// @see tags
		int seeTagsLength = this.seeReferences == null ? 0 : this.seeReferences.length;
		for (int i = 0; i < seeTagsLength; i++) {
			// Resolve reference
			resolveReference(this.seeReferences[i], moduleScope);
		}

		resolveUsesTags(moduleScope, true);
		resolveProvidesTags(moduleScope, true);
	}

	/*
	 * Resolve method javadoc
	 */
	public void resolve(MethodScope methScope) {
		if ((this.bits & ASTNode.ResolveJavadoc) == 0) {
			return;
		}

		this.bits &= ~ASTNode.ResolveJavadoc;// avoid double resolution

		// get method declaration
		AbstractMethodDeclaration methDecl = methScope.referenceMethod();
		boolean overriding = methDecl == null /* field declaration */ || methDecl.binding == null /* compiler error */
			? false :
			!methDecl.binding.isStatic() && ((methDecl.binding.modifiers & (ExtraCompilerModifiers.AccImplementing | ExtraCompilerModifiers.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
			if (methDecl != null && !superRef) {
				if (!methDecl.isConstructor()) {
					if (overriding && 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() && messageSend.actualReceiverType instanceof ReferenceBinding) {
							ReferenceBinding methodReceiverType = (ReferenceBinding) messageSend.actualReceiverType;
							TypeBinding superType = methDecl.binding.declaringClass.findSuperTypeOriginatingFrom(methodReceiverType);
							if (superType != null && TypeBinding.notEquals(superType.original(), methDecl.binding.declaringClass) && CharOperation.equals(messageSend.selector, methDecl.selector)) {
								if (methScope.environment().methodVerifier().doesMethodOverride(methDecl.binding, messageSend.binding.original())) {
									superRef = true;
								}
							}
						}
					}
				} 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()) {
						ReferenceBinding allocType = (ReferenceBinding) allocationExpr.resolvedType.original();
						ReferenceBinding superType = (ReferenceBinding) methDecl.binding.declaringClass.findSuperTypeOriginatingFrom(allocType);
						if (superType != null && TypeBinding.notEquals(superType.original(), methDecl.binding.declaringClass)) {
							MethodBinding superConstructor = methScope.getConstructor(superType, methDecl.binding.parameters, allocationExpr);
							if (superConstructor.isValidBinding() && superConstructor.original() == allocationExpr.binding.original()) {
								MethodBinding current = methDecl.binding;
								// work 'against' better inference in 1.8 (otherwise comparing (G with G) would fail):
								if (methScope.compilerOptions().sourceLevel >= ClassFileConstants.JDK1_8
									&& current.typeVariables != Binding.NO_TYPE_VARIABLES)
								{
									current = current.asRawMethod(methScope.environment());
								}
								if (superConstructor.areParametersEqual(current)) {
									superRef = true;
								}
							}
						}
					}
				}
			}
		}

		// Look at @Override annotations
		if (!superRef && methDecl != null && methDecl.annotations != null) {
			int length = methDecl.annotations.length;
			for (int i=0; i>> 32);
				int end = (int) this.inheritedPositions[i];
				methScope.problemReporter().javadocUnexpectedTag(start, end);
			}
		}

		// @param tags
		CompilerOptions compilerOptions = methScope.compilerOptions();
		resolveParamTags(methScope, reportMissing, compilerOptions.reportUnusedParameterIncludeDocCommentReference /* considerParamRefAsUsage*/);
		resolveTypeParameterTags(methScope, reportMissing && compilerOptions.reportMissingJavadocTagsMethodTypeParameters);

		// @return tags
		if (this.returnStatement == null) {
			if (reportMissing && methDecl != null) {
				if (methDecl.isMethod()) {
					MethodDeclaration meth = (MethodDeclaration) methDecl;
					if (meth.binding.returnType != TypeBinding.VOID) {
						// 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);

		// @value tag
		boolean source15 = compilerOptions.sourceLevel >= ClassFileConstants.JDK1_5;
		if (!source15 && methDecl != null && this.valuePositions != -1) {
			methScope.problemReporter().javadocUnexpectedTag((int)(this.valuePositions>>>32), (int) this.valuePositions);
		}

		// 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, false);
		}
	}

	private void resolveReference(Expression reference, Scope scope) {

		// Perform resolve
		int problemCount = scope.referenceContext().compilationResult().problemCount;
		switch (scope.kind) {
			case Scope.METHOD_SCOPE:
				reference.resolveType((MethodScope)scope);
				break;
			case Scope.CLASS_SCOPE:
				reference.resolveType((ClassScope)scope);
				break;
		}
		boolean hasProblems = scope.referenceContext().compilationResult().problemCount > problemCount;

		// Verify field references
		boolean source15 = scope.compilerOptions().sourceLevel >= ClassFileConstants.JDK1_5;
		int scopeModifiers = -1;
		if (reference instanceof JavadocFieldReference) {
			JavadocFieldReference fieldRef = (JavadocFieldReference) reference;

			// 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 == JavadocTagConstants.TAG_VALUE_VALUE) {
					if (scopeModifiers == -1) scopeModifiers = scope.getDeclarationModifiers();
					scope.problemReporter().javadocInvalidValueReference(fieldRef.sourceStart, fieldRef.sourceEnd, scopeModifiers);
				}
				else if (fieldRef.actualReceiverType != null) {
					if (scope.kind != Scope.MODULE_SCOPE && scope.enclosingSourceType().isCompatibleWith(fieldRef.actualReceiverType)) {
						fieldRef.bits |= ASTNode.SuperAccess;
					}
					ReferenceBinding resolvedType = (ReferenceBinding) fieldRef.actualReceiverType;
					if (CharOperation.equals(resolvedType.sourceName(), fieldRef.token)) {
						fieldRef.methodBinding = scope.getConstructor(resolvedType, Binding.NO_TYPES, fieldRef);
					} else {
						fieldRef.methodBinding = scope.findMethod(resolvedType, fieldRef.token, Binding.NO_TYPES, fieldRef, false);
					}
				}
			}

			// Verify whether field ref should be static or not (for @value tags)
			else if (source15 && fieldRef.binding != null && fieldRef.binding.isValidBinding()) {
				if (fieldRef.tagValue == JavadocTagConstants.TAG_VALUE_VALUE && !fieldRef.binding.isStatic()) {
					if (scopeModifiers == -1) scopeModifiers = scope.getDeclarationModifiers();
					scope.problemReporter().javadocInvalidValueReference(fieldRef.sourceStart, fieldRef.sourceEnd, scopeModifiers);
				}
			}

			// Verify type references
			if (!hasProblems && fieldRef.binding != null && fieldRef.binding.isValidBinding() && fieldRef.actualReceiverType instanceof ReferenceBinding) {
				ReferenceBinding resolvedType = (ReferenceBinding) fieldRef.actualReceiverType;
				verifyTypeReference(fieldRef, fieldRef.receiver, scope, source15, resolvedType, fieldRef.binding.modifiers);
			}

			// That's it for field references
			return;
		}

		// Verify type references
		if (!hasProblems && (reference instanceof JavadocSingleTypeReference || reference instanceof JavadocQualifiedTypeReference) && reference.resolvedType instanceof ReferenceBinding) {
			ReferenceBinding resolvedType = (ReferenceBinding) reference.resolvedType;
			verifyTypeReference(reference, reference, scope, source15, resolvedType, resolvedType.modifiers);
		}

		if (!hasProblems && (reference instanceof JavadocModuleReference)) {
			JavadocModuleReference ref= (JavadocModuleReference)reference;
			ref.resolve(scope);
			ModuleReference mRef = ref.getModuleReference();
			if (mRef != null) {
				ModuleBinding mType = mRef.resolve(scope);
				if (mType != null && verifyModuleReference(reference, reference, scope, source15, mType, mType.modifiers)) {
					TypeReference tRef= ref.getTypeReference();
					if ((tRef instanceof JavadocSingleTypeReference || tRef instanceof JavadocQualifiedTypeReference) && tRef.resolvedType instanceof ReferenceBinding) {
						ReferenceBinding resolvedType = (ReferenceBinding) tRef.resolvedType;
						verifyTypeReference(reference, reference, scope, source15, resolvedType, resolvedType.modifiers);
					}
				}
			}
		}

		// Verify that message reference are not used for @value tags
		if (reference instanceof JavadocMessageSend) {
			JavadocMessageSend msgSend = (JavadocMessageSend) reference;

			// tag value
			if (source15 && msgSend.tagValue == JavadocTagConstants.TAG_VALUE_VALUE) { // cannot refer to method for @value tag
				if (scopeModifiers == -1) scopeModifiers = scope.getDeclarationModifiers();
				scope.problemReporter().javadocInvalidValueReference(msgSend.sourceStart, msgSend.sourceEnd, scopeModifiers);
			}

			// Verify type references
			if (!hasProblems && msgSend.binding != null && msgSend.binding.isValidBinding() && msgSend.actualReceiverType instanceof ReferenceBinding) {
				ReferenceBinding resolvedType = (ReferenceBinding) msgSend.actualReceiverType;
				verifyTypeReference(msgSend, msgSend.receiver, scope, source15, resolvedType, msgSend.binding.modifiers);
			}
		}

		// Verify that constructor reference are not used for @value tags
		else if (reference instanceof JavadocAllocationExpression) {
			JavadocAllocationExpression alloc = (JavadocAllocationExpression) reference;

			// tag value
			if (source15 && alloc.tagValue == JavadocTagConstants.TAG_VALUE_VALUE) { // cannot refer to method for @value tag
				if (scopeModifiers == -1) scopeModifiers = scope.getDeclarationModifiers();
				scope.problemReporter().javadocInvalidValueReference(alloc.sourceStart, alloc.sourceEnd, scopeModifiers);
			}

			// Verify type references
			if (!hasProblems && alloc.binding != null && alloc.binding.isValidBinding() && alloc.resolvedType instanceof ReferenceBinding) {
				ReferenceBinding resolvedType = (ReferenceBinding) alloc.resolvedType;
				verifyTypeReference(alloc, alloc.type, scope, source15, resolvedType, alloc.binding.modifiers);
			}
		}

		// Verify that there's no type variable reference
		// (javadoc does not accept them and this is not a referenced bug or requested enhancement)
		else if (reference instanceof JavadocSingleTypeReference && reference.resolvedType != null && reference.resolvedType.isTypeVariable()) {
			scope.problemReporter().javadocInvalidReference(reference.sourceStart, reference.sourceEnd);
		}
	}

	/*
	 * Resolve @param tags while method scope
	 */
	private void resolveParamTags(MethodScope scope, boolean reportMissing, boolean considerParamRefAsUsage) {
		AbstractMethodDeclaration methodDecl = scope.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 (methodDecl == null) {
			for (int i = 0; i < paramTagsSize; i++) {
				JavadocSingleNameReference param = this.paramReferences[i];
				scope.problemReporter().javadocUnexpectedTag(param.tagSourceStart, param.tagSourceEnd);
			}
			return;
		}

		// If no param tags then report a problem for each method argument
		int argumentsSize = methodDecl.arguments == null ? 0 : methodDecl.arguments.length;
		if (paramTagsSize == 0) {
			if (reportMissing) {
				for (int i = 0; i < argumentsSize; i++) {
					Argument arg = methodDecl.arguments[i];
					scope.problemReporter().javadocMissingParamTag(arg.name, arg.sourceStart, arg.sourceEnd, methodDecl.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(scope, true, considerParamRefAsUsage);
				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) {
							scope.problemReporter().javadocDuplicatedParamTag(param.token, param.sourceStart, param.sourceEnd, methodDecl.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 = methodDecl.arguments[i];
					boolean found = false;
					for (int j = 0; j < maxBindings; j++) {
						LocalVariableBinding binding = bindings[j];
						if (arg.binding == binding) {
							found = true;
							break;
						}
					}
					if (!found) {
						scope.problemReporter().javadocMissingParamTag(arg.name, arg.sourceStart, arg.sourceEnd, methodDecl.binding.modifiers);
					}
				}
			}
		}
	}

	/*
	 * Resolve @uses tags while block scope
	 */
	private void resolveUsesTags(BlockScope scope, boolean reportMissing) {
		ModuleDeclaration moduleDecl = (ModuleDeclaration)scope.referenceContext();
		int usesTagsSize = this.usesReferences == null ? 0 : this.usesReferences.length;

		// If no referenced module then report a problem for each uses tag
		if (moduleDecl == null) {
			for (int i = 0; i < usesTagsSize; i++) {
				IJavadocTypeReference uses = this.usesReferences[i];
				scope.problemReporter().javadocUnexpectedTag(uses.getTagSourceStart(), uses.getTagSourceEnd());
			}
			return;
		}

		// If no uses tags then report a problem for each uses reference
		int usesSize = moduleDecl.usesCount;
		if (usesTagsSize == 0) {
			if (reportMissing) {
				for (int i = 0; i < usesSize; i++) {
					UsesStatement uses = moduleDecl.uses[i];
					scope.problemReporter().javadocMissingUsesTag(uses.serviceInterface, uses.sourceStart, uses.sourceEnd, moduleDecl.binding.modifiers);
				}
			}
		} else {
			TypeBinding[] bindings = new TypeBinding[usesTagsSize];
			int maxBindings = 0;

			// Scan all @uses tags
			for (int i = 0; i < usesTagsSize; i++) {
				TypeReference usesRef = (TypeReference)this.usesReferences[i];
				try {
					usesRef.resolve(scope);
					if (usesRef.resolvedType != null && usesRef.resolvedType.isValidBinding()) {
						// Verify duplicated tags
						boolean found = false;
						for (int j = 0; j < maxBindings && !found; j++) {
							if (bindings[j].equals(usesRef.resolvedType)) {
								scope.problemReporter().javadocDuplicatedUsesTag(usesRef.sourceStart, usesRef.sourceEnd);
								found = true;
							}
						}
						if (!found) {
							bindings[maxBindings++] = usesRef.resolvedType;
						}
					}
				} catch (Exception e) {
					scope.problemReporter().javadocInvalidUsesClass(usesRef.sourceStart, usesRef.sourceEnd);
				}
			}

			// Look for undocumented uses
			if (reportMissing) {
				for (int i = 0; i < usesSize; i++) {
					UsesStatement uses = moduleDecl.uses[i];
					boolean found = false;
					for (int j = 0; j < maxBindings && !found; j++) {
						TypeBinding binding = bindings[j];
						if (uses.serviceInterface.getTypeBinding(scope).equals(binding)) {
							found = true;
						}
					}
					if (!found) {
						scope.problemReporter().javadocMissingUsesTag(uses.serviceInterface, uses.sourceStart, uses.sourceEnd, moduleDecl.binding.modifiers);
					}
				}
			}
		}
	}

	/*
	 * Resolve @provides tags while block scope
	 */
	private void resolveProvidesTags(BlockScope scope, boolean reportMissing) {
		ModuleDeclaration moduleDecl = (ModuleDeclaration)scope.referenceContext();
		int providesTagsSize = this.providesReferences == null ? 0 : this.providesReferences.length;

		// If no referenced module then report a problem for each uses tag
		if (moduleDecl == null) {
			for (int i = 0; i < providesTagsSize; i++) {
				IJavadocTypeReference provides = this.providesReferences[i];
				scope.problemReporter().javadocUnexpectedTag(provides.getTagSourceStart(), provides.getTagSourceEnd());
			}
			return;
		}

		// If no uses tags then report a problem for each uses reference
		int providesSize = moduleDecl.servicesCount;
		if (providesTagsSize == 0) {
			if (reportMissing) {
				for (int i = 0; i < providesSize; i++) {
					ProvidesStatement provides = moduleDecl.services[i];
					scope.problemReporter().javadocMissingProvidesTag(provides.serviceInterface, provides.sourceStart, provides.sourceEnd, moduleDecl.binding.modifiers);
				}
			}
		} else {
			TypeBinding[] bindings = new TypeBinding[providesTagsSize];
			int maxBindings = 0;

			// Scan all @provides tags
			for (int i = 0; i < providesTagsSize; i++) {
				TypeReference providesRef = (TypeReference)this.providesReferences[i];
				try {
					providesRef.resolve(scope);
					if (providesRef.resolvedType != null && providesRef.resolvedType.isValidBinding()) {
						// Verify duplicated tags
						boolean found = false;
						for (int j = 0; j < maxBindings && !found; j++) {
							if (bindings[j].equals(providesRef.resolvedType)) {
								scope.problemReporter().javadocDuplicatedProvidesTag(providesRef.sourceStart, providesRef.sourceEnd);
								found = true;
							}
						}
						if (!found) {
							bindings[maxBindings++] = providesRef.resolvedType;
						}
					}
				} catch (Exception e) {
					scope.problemReporter().javadocInvalidProvidesClass(providesRef.sourceStart, providesRef.sourceEnd);
				}
			}

			// Look for undocumented uses
			if (reportMissing) {
				for (int i = 0; i < providesSize; i++) {
					ProvidesStatement provides = moduleDecl.services[i];
					boolean found = false;
					for (int j = 0; j < maxBindings && !found; j++) {
						TypeBinding binding = bindings[j];
						if (provides.serviceInterface.getTypeBinding(scope).equals(binding)) {
							found = true;
						}
					}
					if (!found) {
						scope.problemReporter().javadocMissingProvidesTag(provides.serviceInterface, provides.sourceStart, provides.sourceEnd, moduleDecl.binding.modifiers);
					}
				}
			}
		}
	}

	/*
	 * Resolve @param tags for type parameters
	 */
	private void resolveTypeParameterTags(Scope scope, boolean reportMissing) {
		int paramTypeParamLength = this.paramTypeParameters == null ? 0 : this.paramTypeParameters.length;
		int paramReferencesLength = this.paramReferences == null ? 0 : this.paramReferences.length;

		// Get declaration infos
		TypeParameter[] parameters = null;
		TypeVariableBinding[] typeVariables = null;
		RecordComponent[] recordParameters = null;
		int modifiers = -1;
		switch (scope.kind) {
			case Scope.METHOD_SCOPE:
				AbstractMethodDeclaration 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++) {
						JavadocSingleTypeReference param = this.paramTypeParameters[i];
						scope.problemReporter().javadocUnexpectedTag(param.tagSourceStart, param.tagSourceEnd);
					}
					return;
				}
				parameters = methodDeclaration.typeParameters();
				typeVariables = methodDeclaration.binding.typeVariables;
				modifiers = methodDeclaration.binding.modifiers;
				break;
			case Scope.CLASS_SCOPE:
				TypeDeclaration typeDeclaration = ((ClassScope) scope).referenceContext;
				parameters = typeDeclaration.typeParameters;
				typeVariables = typeDeclaration.binding.typeVariables;
				modifiers = typeDeclaration.binding.modifiers;
				recordParameters = typeDeclaration.recordComponents;
				break;
		}

		// If no type variables then report a problem for each param type parameter tag
		if ((recordParameters == null || recordParameters.length == 0)
				&& (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 record parameter
		if (recordParameters != null) {
			reportMissing = reportMissing && scope.compilerOptions().sourceLevel >= ClassFileConstants.JDK1_5;
			int recordParametersLength = recordParameters.length;
			String argNames[] = new String[paramReferencesLength];
			if (paramReferencesLength == 0) {
				if (reportMissing) {
					for (int i = 0, l=recordParametersLength; i= ClassFileConstants.JDK1_5;
			int typeParametersLength = parameters.length;
			if (paramTypeParamLength == 0) {
				if (reportMissing) {
					for (int i = 0, l=typeParametersLength; i= 0;) {
					computedCompoundName[--idx] = topLevelType.fPackage.compoundName[i];
				}

				if (scope.kind != Scope.MODULE_SCOPE) {
					ClassScope topLevelScope = scope.classScope();
					// when scope is not on compilation unit type, then inner class may not be visible...
					if (topLevelScope.parent.kind != Scope.COMPILATION_UNIT_SCOPE ||
						!CharOperation.equals(topLevelType.sourceName, topLevelScope.referenceContext.name)) {
						topLevelScope = topLevelScope.outerMostClassScope();
						if (typeReference instanceof JavadocSingleTypeReference) {
							// inner class single reference can only be done in same unit
							if ((!source15 && depth == 1) || TypeBinding.notEquals(topLevelType, topLevelScope.referenceContext.binding)) {
								// search for corresponding import
								boolean hasValidImport = false;
								if (source15) {
									CompilationUnitScope unitScope = topLevelScope.compilationUnitScope();
									ImportBinding[] imports = unitScope.imports;
									int length = imports == null ? 0 : imports.length;
									mainLoop: for (int i=0; i= 0;) {
												if (CharOperation.equals(imports[i].compoundName[j], computedCompoundName[j])) {
													if (j == 0) {
														hasValidImport = true;
														ImportReference importReference = imports[i].reference;
														if (importReference != null) {
															importReference.bits |= ASTNode.Used;
														}
														break mainLoop;
													}
												} else {
													break;
												}
											}
										}
									}
									if (!hasValidImport) {
										if (scopeModifiers == -1) scopeModifiers = scope.getDeclarationModifiers();
										scope.problemReporter().javadocInvalidMemberTypeQualification(typeReference.sourceStart, typeReference.sourceEnd, scopeModifiers);
									}
								} else {
									if (scopeModifiers == -1) scopeModifiers = scope.getDeclarationModifiers();
									scope.problemReporter().javadocInvalidMemberTypeQualification(typeReference.sourceStart, typeReference.sourceEnd, scopeModifiers);
									return;
								}
							}
						}
					}
					if (typeReference instanceof JavadocQualifiedTypeReference && !scope.isDefinedInSameUnit(resolvedType)) {
						// https://bugs.eclipse.org/bugs/show_bug.cgi?id=222188
						// partially qualified references from a different CU should be warned
						char[][] typeRefName = ((JavadocQualifiedTypeReference) typeReference).getTypeName();
						int skipLength = 0;
						if (topLevelScope.getCurrentPackage() == resolvedType.getPackage()
								&& typeRefName.length < computedCompoundName.length) {
							// https://bugs.eclipse.org/bugs/show_bug.cgi?id=221539: references can be partially qualified
							// in same package and hence if the package name is not given, ignore package name check
							skipLength = resolvedType.fPackage.compoundName.length;
						}
						boolean valid = true;
						if (typeRefName.length == computedCompoundName.length - skipLength) {
							checkQualification: for (int i = 0; i < typeRefName.length; i++) {
								if (!CharOperation.equals(typeRefName[i], computedCompoundName[i + skipLength])) {
									valid = false;
									break checkQualification;
								}
							}
						} else {
							valid = false;
						}
						// report invalid reference
						if (!valid) {
							if (scopeModifiers == -1) scopeModifiers = scope.getDeclarationModifiers();
							scope.problemReporter().javadocInvalidMemberTypeQualification(typeReference.sourceStart, typeReference.sourceEnd, scopeModifiers);
							return;
						}
					}
				}
			}
			/*
			 * https://bugs.eclipse.org/bugs/show_bug.cgi?id=286918
			 *
			 * We are concerned only about the Single type references (i.e. without any package) If they are not in default package,
			 * then report an error. References with qualified yet incorrect names would have already been taken care of.
			 */
			if (scope.referenceCompilationUnit().isPackageInfo() && typeReference instanceof JavadocSingleTypeReference) {
				if (resolvedType.fPackage.compoundName.length > 0) {
					scope.problemReporter().javadocInvalidReference(typeReference.sourceStart, typeReference.sourceEnd);
					return; // Not really needed - just in case more code added in future
				}
			}
		}
	}

	private boolean verifyModuleReference(Expression reference, Expression typeReference, Scope scope, boolean source15, ModuleBinding moduleType, int modifiers) {
		boolean bindingFound = false;
		if (moduleType!= null && moduleType.isValidBinding()) {
			int scopeModifiers = -1;

			ModuleBinding mBinding = scope.module();

			if (mBinding == null) {
				scope.problemReporter().javadocInvalidModuleQualification(typeReference.sourceStart, typeReference.sourceEnd, scopeModifiers);
				return bindingFound;
			}

			if (mBinding.equals(moduleType)) {
				bindingFound = true;
			} else {
				ModuleBinding[] bindings = mBinding.getAllRequiredModules();
				for (ModuleBinding binding : bindings) {
					if (moduleType.equals(binding)) {
						bindingFound = true;
						break;
					}
				}
			}

			if (!bindingFound) {
				if (!canBeSeen(scope.compilerOptions().reportInvalidJavadocTagsVisibility, moduleType.modifiers)) {
					scope.problemReporter().javadocHiddenReference(typeReference.sourceStart, typeReference.sourceEnd, scope, moduleType.modifiers);
					return bindingFound;
				}
			}
		}
		return bindingFound;
	}

	@Override
	public void traverse(ASTVisitor visitor, BlockScope scope) {
		if (visitor.visit(this, scope)) {
			if (this.paramReferences != null) {
				for (JavadocSingleNameReference paramReference : this.paramReferences) {
					paramReference.traverse(visitor, scope);
				}
			}
			if (this.paramTypeParameters != null) {
				for (JavadocSingleTypeReference paramTypeParameter : this.paramTypeParameters) {
					paramTypeParameter.traverse(visitor, scope);
				}
			}
			if (this.returnStatement != null) {
				this.returnStatement.traverse(visitor, scope);
			}
			if (this.exceptionReferences != null) {
				for (TypeReference exceptionReference : this.exceptionReferences) {
					exceptionReference.traverse(visitor, scope);
				}
			}
			if (this.seeReferences != null) {
				for (Expression seeReference : this.seeReferences) {
					seeReference.traverse(visitor, scope);
				}
			}
		}
		visitor.endVisit(this, scope);
	}
	public void traverse(ASTVisitor visitor, ClassScope scope) {
		if (visitor.visit(this, scope)) {
			if (this.paramReferences != null) {
				for (JavadocSingleNameReference paramReference : this.paramReferences) {
					paramReference.traverse(visitor, scope);
				}
			}
			if (this.paramTypeParameters != null) {
				for (JavadocSingleTypeReference paramTypeParameter : this.paramTypeParameters) {
					paramTypeParameter.traverse(visitor, scope);
				}
			}
			if (this.returnStatement != null) {
				this.returnStatement.traverse(visitor, scope);
			}
			if (this.exceptionReferences != null) {
				for (TypeReference exceptionReference : this.exceptionReferences) {
					exceptionReference.traverse(visitor, scope);
				}
			}
			if (this.seeReferences != null) {
				for (Expression seeReference : this.seeReferences) {
					seeReference.traverse(visitor, scope);
				}
			}
		}
		visitor.endVisit(this, scope);
	}
}
    

    

    

            

    

            



    
    






    
© 2015 - 2024 Weber Informatics LLC | Privacy Policy