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

[Jonathan Gibbons]

On 08/24/2013 04:19 PM, Werner Dietl wrote:
> On Sat, Aug 24, 2013 at 4:05 PM, Jonathan Gibbons
> <jonathan.gibbons at oracle.com> wrote:
>> 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
>
> My interpretation is that
> com.sun.source.tree.NewClassTree.getTypeArguments() returns the type
> arguments of the constructor itself, not of the type being
> instantiated.
> So in "new ArrayList<String>()" I expect
> NewClassTree.getTypeArguments() to return an empty List and
> getIdentifier() to return the Tree "ArrayList<String>".
>
> If we have "new @TA ArrayList<String>()" getIdentifier() will return
> the instantiated type, including the type annotation.
>
> Looking at a few uses of com.sun.tools.javac.tree.JCTree.JCNewClass, e.g. in
> com.sun.tools.javac.comp.Attr.visitNewClass(JCNewClass)
> you will see code like:
>
>          if (clazz.hasTag(TYPEAPPLY)) {
>
> So it seems like it is expected that clazz has type arguments.

Yes, OK.  noted.  I guess this all deserves a clean-up when JLS 8 is
available, when we can at least work against a single self-consistent
version of the grammar.

I still don't think we can/should change the method names (yet) but
I do think we should do a better job of typing them back to the
various grammar productions.

-- Jon


>
>
>> If it is returning type annotations and type arguments, that would
>> warrant a raised eyebrow and further investigation.
> Raised?
>
> cu, WMD.
>
>
>
>>> 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
>>>
>>>
>
>