Javadoc and @since in com.sun.source.tree

[Jonathan Gibbons]

On 08/02/2013 02:10 PM, Werner Dietl wrote:
> Jon,
>
> I've added two @since annotations and javadoc:
>
> http://hg.openjdk.java.net/type-annotations/type-annotations/langtools/rev/342d34b65fd8
>
> Please have a look. I added some comments about the new TYPE_USE and
> TYPE_PARAMETER target. Maybe that should we added just once, somewhere
> else? Feel free to edit/remove this.
>
> Only few changes were required, as most methods return a generic Tree
> and can automatically return annotated type trees.
>
> I have one question: method
>
> com.sun.source.tree.NewClassTree.getIdentifier()
>
> actually returns the type of the instantiation - including type
> annotations, type arguments, etc.

Really?  From both the javadoc on NewClassTree, and from a
superficial look at the impl, I would expect getIdentifier to return
the name of the class being instantiation.  Admittedly, "identifier"
seems simplistic, but it is in line with the usage in JLS 15.9

If it is returning type annotations and type arguments, that would
warrant a raised eyebrow and further investigation.



> In contrast, method
>
> com.sun.source.tree.NewArrayTree.getType()
>
> presumably does the same thing, i.e. returns the array component type.

It should return the element type without any dimension info.

>
> Why is one named getIdentifier() and one getType()?

The interfaces in com.sun.source.tree were (generally) based
on the BNF rules in JLS 3 (which was current at the time the API
was designed.)  Although the methods do not have much (if any)
javadoc, in general, there should be class level docs, citing the
relevant JLS sections and grammar rules, and there should be a
strong correspondence between the words in the grammar rules in
the doc comments and the method names.

Alex, has done a lot of work for JLS 8, rationalizing the grammar
rules in JLS, and at some point it might be worth reflecting that in the
comments on com.sun.source.tree.  I'm not sure how much we
can/want to change the method names, but bringing the javadoc
comments up to date with the corresponding JLS sections would be
good, and we could give additional details when the declared method
name is at variance with the word in the grammar production.

HTH.


> Should getIdentifier() not return type annotations?
> Some javadoc on these methods would help :-)
>
> cu, WMD.
>
> On Mon, Jul 29, 2013 at 5:55 PM, Jonathan Gibbons
> <jonathan.gibbons at oracle.com> wrote:
>> On 07/29/2013 05:44 PM, Werner Dietl wrote:
>>> JSR 308 added a few methods/enum constants in com.sun.source.tree, e.g.:
>>>
>>> com.sun.source.tree.Tree.Kind.ANNOTATED_TYPE
>>> com.sun.source.tree.TypeParameterTree.getAnnotations()
>>>
>>> These currently have no Javadoc (which is consistent with the lack of
>>> Javadoc in other such classes) and no @since 1.8.
>>> As these classes are @jdk.Supported, I think it would be nice to
>>> document our changes.
>>> Should I add some first blurbs or is somebody else better suited?
>>>
>>> Cheers,
>>> cu, WMD.
>>>
>> If you put @since on the new items, I'll put @since on the older items.
>>
>> -- Jon
>
>