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.
org.eclipse.jdt.internal.compiler.ast.Javadoc Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2000, 2009 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-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.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 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;
}
/**
* 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 (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
*/
public void resolve(ClassScope scope) {
// 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++) {
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) {
// 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 method javadoc
*/
public void resolve(MethodScope methScope) {
// 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 && 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 && superType.original() != methDecl.binding.declaringClass) {
MethodBinding superConstructor = methScope.getConstructor(superType, methDecl.binding.parameters, allocationExpr);
if (superConstructor.isValidBinding() && superConstructor.original() == allocationExpr.binding.original()) {
if (superConstructor.areParametersEqual(methDecl.binding)) {
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);
// @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.enclosingSourceType().isCompatibleWith(fieldRef.actualReceiverType)) {
fieldRef.bits |= ASTNode.SuperAccess;
}
fieldRef.methodBinding = scope.findMethod((ReferenceBinding)fieldRef.actualReceiverType, fieldRef.token, new TypeBinding[0], fieldRef);
}
}
// 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);
}
// 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)
if (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 && !found; j++) {
LocalVariableBinding binding = bindings[j];
if (arg.binding == binding) {
found = true;
}
}
if (!found) {
scope.problemReporter().javadocMissingParamTag(arg.name, arg.sourceStart, arg.sourceEnd, methodDecl.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
TypeParameter[] parameters = null;
TypeVariableBinding[] typeVariables = 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;
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
if (parameters != null) {
int typeParametersLength = parameters.length;
if (paramTypeParamLength == 0) {
if (reportMissing) {
for (int i = 0, l=typeParametersLength; i= 0;) {
computedCompoundName[--idx] = topLevelType.fPackage.compoundName[i];
}
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) || 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;
}
}
}
}
}
}
}
public void traverse(ASTVisitor visitor, BlockScope scope) {
if (visitor.visit(this, scope)) {
if (this.paramReferences != null) {
for (int i = 0, length = this.paramReferences.length; i < length; i++) {
this.paramReferences[i].traverse(visitor, scope);
}
}
if (this.paramTypeParameters != null) {
for (int i = 0, length = this.paramTypeParameters.length; i < length; i++) {
this.paramTypeParameters[i].traverse(visitor, scope);
}
}
if (this.returnStatement != null) {
this.returnStatement.traverse(visitor, scope);
}
if (this.exceptionReferences != null) {
for (int i = 0, length = this.exceptionReferences.length; i < length; i++) {
this.exceptionReferences[i].traverse(visitor, scope);
}
}
if (this.seeReferences != null) {
for (int i = 0, length = this.seeReferences.length; i < length; i++) {
this.seeReferences[i].traverse(visitor, scope);
}
}
}
visitor.endVisit(this, scope);
}
public void traverse(ASTVisitor visitor, ClassScope scope) {
if (visitor.visit(this, scope)) {
if (this.paramReferences != null) {
for (int i = 0, length = this.paramReferences.length; i < length; i++) {
this.paramReferences[i].traverse(visitor, scope);
}
}
if (this.paramTypeParameters != null) {
for (int i = 0, length = this.paramTypeParameters.length; i < length; i++) {
this.paramTypeParameters[i].traverse(visitor, scope);
}
}
if (this.returnStatement != null) {
this.returnStatement.traverse(visitor, scope);
}
if (this.exceptionReferences != null) {
for (int i = 0, length = this.exceptionReferences.length; i < length; i++) {
this.exceptionReferences[i].traverse(visitor, scope);
}
}
if (this.seeReferences != null) {
for (int i = 0, length = this.seeReferences.length; i < length; i++) {
this.seeReferences[i].traverse(visitor, scope);
}
}
}
visitor.endVisit(this, scope);
}
}
