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

[Werner Dietl]

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.


> 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
>>
>>
>>
>



-- 
http://www.google.com/profiles/wdietl