Community
Participate
Working Groups
HEAD In the ASTNode APIs, all fields and static accessors of type StructuralPropertyDescriptor (or a subtype thereof) should specify the type of elements the property holds. This information is already stored in the implementation, but is always a pain that it's not readily available in the API documentation. Example: - MethodDeclaration#typeParameters() specifies: (element type: <code>TypeParameter</code>) => better: (element type: {@link TypeParameter}) - MethodDeclaration#TYPE_PARAMETERS_PROPERTY specifies: The "typeParameters" structural property of this node type => should say: The "typeParameters" structural property of this node type (element type: {@link TypeParameter}) Likewise, accessors for inherited properties should be documented, e.g.: - BodyDeclaration#getJavadocProperty() and MethodDeclaration#JAVADOC_PROPERTY => should say: (child type: {@link Javadoc}) Note: This bug becomes obsolete when the DOM APIs are generified (which would also be a very welcome solution).
Created attachment 178084 [details] Proposed fix
Released for 3.7M2. Verification has to be done by code inspection.
Looks mostly good, but I disagree with the description of properties with a primitive type. The Javadoc should not use the boxed type. The setters and getters that use property descriptors deal with the boxing/unboxing. E.g. BooleanLiteral#BOOLEAN_VALUE_PROPERTY says "(type: {@link Boolean})", but the SimplePropertyDescriptor is created with "boolean.class" and thus SimplePropertyDescriptor#getValueType() also returns "boolean.class" and not "Boolean.class". Regex to narrow down the places that need adjustments: \b[a-z]+\.class\b
So you suggest: (type: {@link boolean.class}) ?
> (type: {@link boolean.class}) Unfortunately, Javadoc can't create @link links to primitive types, so it would be (type: <code>boolean</code>). But thinking about it again, we should probably leave it as you did it. When SimplePropertyDescriptor gets generified, the type argument for boolean properties will also be Boolean and not boolean. Marking as fixed again.
Verified for 3.7M2 using code inspection.
