Community
Participate
Working Groups
Follow-up to bug 210565 comment 9 > I don't think that we can refer to compile-time constants here since the user > can put anything (for example the user forgot .class in the following case: > @MyAnnot(clazz=Object) ) That argument would apply to the other value kinds as well. E.g. @SuppressWarnings(@Bla) or @SuppressWarnings(Bla.class) also result in the syntactically correct value kinds, but they don't resolve when compiled. At least you should remove the "Especially" and replace it by "For example,". And please also fix the wrong note in K_CLASS (attachment 85192 [details]).
(In reply to comment #0) > Follow-up to bug 210565 comment 9 > > > I don't think that we can refer to compile-time constants here since the user > > can put anything (for example the user forgot .class in the following case: > > @MyAnnot(clazz=Object) ) > > That argument would apply to the other value kinds as well. E.g. > @SuppressWarnings(@Bla) or @SuppressWarnings(Bla.class) also result in the > syntactically correct value kinds, but they don't resolve when compiled. I just meant that we cannot say that the simple name is a compile-time constant. In the case of @SuppressWarnings(@Bla), @Bla is for sure an annotation and in the case of @SuppressWarnings(Bla.class), Blass.class is for sure a class literal. > At least you should remove the "Especially" and replace it by "For example,". Maxime, it looks like using "especially" as you suggested is not clear for all. What do you think? > And please also fix the wrong note in K_CLASS (attachment 85192 [details]). I'm not sure to understand why the note is wrong. Can you please explain?
(In reply to comment #1) > > At least you should remove the "Especially" and replace it by "For example,". > Maxime, it looks like using "especially" as you suggested is not clear for all. > What do you think? We decided for especially because you wanted to put a specific emphasis on that use case. According to Merriam-Webster, our proposal is correct and conveys your intent. If this confuses some readers, you may want to change it anyway. I fear that 'For example,' would miss your point. One trick you could try would be to use simpler words (aka get rid of especially), but to complete them by a more verbose writing, starting with 'An example of interest...' for example. Another trick would be to give more than one example in a way that makes clear that you do not aim at listing all possible use cases, and to keep 'especially' to emphasize the use case that triggered the API introduction, but that would obviously result into a longer text.
(In reply to comment #1) > > And please also fix the wrong note in K_CLASS (attachment 85192 [details] [details]). > I'm not sure to understand why the note is wrong. Can you please explain? Is: "Note that one can use {@link IType#resolveType(String)} to find the corresponding {@link IType}." Problem: The return type of IType#resolveType(String) is String[][], so this method alone is not enough to find the corresponding IType. Proposed solution: "Note that one can use {@link IType#resolveType(String)} and e.g. {@link IJavaProject#findType(String, String, org.eclipse.core.runtime.IProgressMonitor)} to find the corresponding {@link IType}." => Tells the user how to find an IType for the String[][]
> I just meant that we cannot say that the simple name is a compile-time > constant. In the case of @SuppressWarnings(@Bla), @Bla is for sure an > annotation and in the case of @SuppressWarnings(Bla.class), Blass.class is for > sure a class literal. That's why I added "(unresolved)" in "This represents an (unresolved) reference to a compile-time constant". Even if the simple name is e.g. "Object", it can still only be a reference to a compile-time constant. It can never be a reference to e.g. a type. I still think the current "Especially" makes little sense. That the simple name is "FIRST" is not a special or common case - it's only an example of the only correct case (where the name refers to a constant). To make this explicit, you could say: "The name refers to a compile-time constant, unless there's a compile error."
(In reply to comment #4) > I still think the current "Especially" makes little sense. That the simple name > is "FIRST" is not a special or common case - it's only an example of the only > correct case (where the name refers to a constant). The complete sentence reads 'Especially if the simple name is "FIRST" and there is a static import for "MyEnum.FIRST", this can represent an enumeration's constant.' This is because the feature was introduced to support enumerations and Jérôme wanted to emphasize this. But there would still be use cases that are not related to enumerations (aka static final fields, see bug 210565 comment #5 example). Hence the use of especially. My comments about possible variants above still apply though.
How about fixing Jerome's initial suggestion (bug 210565 comment 1): 'The simple name refers to an enum constant or another compile-time constant if the code is correct (e.g. "FIRST" when there is a static import for "MyEnum.FIRST").' => Makes no guesses and is simple and correct iff the code compiles. "Especially" followed by a concrete example is just wrong, because the example is *not* special. But I won't spend more time on this argument any more.
(In reply to comment #6) > How about fixing Jerome's initial suggestion (bug 210565 comment 1): > 'The simple name refers to an enum constant or another compile-time constant if > the code is correct (e.g. "FIRST" when there is a static import for > "MyEnum.FIRST").' > => Makes no guesses and is simple and correct iff the code compiles. I like it. > "Especially" followed by a concrete example is just wrong, because the example > is *not* special. But I won't spend more time on this argument any more. Again, especially does not systematically imply that you're talking about anything 'special'. Merriam-Webster states (amongst other definitions) that especially can stand for 'in particular', which merely marks the intent of the writer to insist on a specific case (that has nothing special beyond the intent of the author to insist on it). Agree that this does not deserve too long a discussion though ;-)
Created attachment 88122 [details] Fix Here's a patch that implements comment 6 (Maxime said: "I like it.") and comment 3.
Thanks Markus. Patch released for 3.4M5.
Verified for 3.4M5 using I20080204-0010
