Community
Participate
Working Groups
I20080226-1155. The new API tooling is based on tags that forbid things (@noimplement, @noinstantiate, @noextend). Unfortunately this does not play well with the Eclipse API guidelines: http://www.eclipse.org/articles/article.php?file=Article-API-Use/index.html In those guidelines everything is forbidden by default unless otherwise stated in the Javadoc, e.g.: >Classes that are designed to be subclassed by clients are explicitly flagged in >the Javadoc class comment (with words like "Clients may subclass."). Look at this example: /** * A class. */ public class A { } ==> according to the API guidelines this class is not allowed to be subclassed. With the introduction of API tooling this is now considered to be subclassable as there are not tags prohibiting this. I marked this bug critical because I cannot yet see how the tooling plays together with the Eclipse API guidelines. Also, it's not clear whether we only have to use the tags or whether we still have to put the verbose text into the Javadoc. In case of mismatch between tags and verbose Javadoc it's also not clear for clients which version wins.
Looking at the Eclipse SDK there are lots of cases where classes are subclassed that do not explicitly allow this in the Javadoc. Maybe it would be a good point in time now to adjust the guidelines to say that when using API tags, everything is allowed if there is no tag. Somewhere (e.g. manifest.mf) a project would have to specify whether they use API guideline version 1.0 or 2.0. Adding Jeem who wrote the guidelines.
Removing critical. I disagree. API tooling is based on explicit API descriptions. We have many cases were classes not documented with explicit restrictions means there are no restrictions. I recall forgetting to put restrictions on classes in javadoc, and then having to get PMC approval to add restrictions in a later release - which was considered a breaking change.
We wrote our restrictions based on what was done for the component.xml file and it was clear at that time that no restrictions meant that implement, extends or instantiate was allowed. If by default all restrictions are on, why the restrictions are explicitly specified in the Eclipse javadoc APIs?
The tooling could be made extensible/customizeable to allow for different tags/comments, or to allow for "no tag" to mean specific things. However, I'm not sure it's a good idea as those settings would always have to be shipped with the source code in order for tools to interpret the tags (or lack of tags) - for example, source import. Having standard/explicit tags makes the documentation more portable/re-useable. Marking as won't fix.
Then at least the API guidelines should be updated to be in sync.
*** Bug 225756 has been marked as a duplicate of this bug. ***
I agree with Dani that we should update the guidelines. Being restrictive by default makes sense, but only if everybody knows about the rules and plays by it. It seems to me that the "crowd" has decided to not play by these rules. So, +1 for keeping the tags as they are, but also +1 for updating the guidelines.
+1 on updating the guidelines. I think we should encourage people writing Javadoc to always be explicit, rather than rely on some global default rule that the reader might or might not know about. But clearly we can't require them to do so at this point.
Maybe the updated doc can say that if a project uses API tooling (tags) then those tags describes the API contract. The problem is if no tags are found: how can a client know that API tooling was used but there's no restriction?
Reopening so that those who promote breakage of the original API rules don't forget to update the rules in public.
Assigning to me. I spent some time with Jim on Friday on this, but I haven't found the time to make the actual updates to the document. Markus, are you saying that JDT UI relied on the guidelines, i.e. do you have public classes that you do not consider subclassable but the Javadoc does not state that restriction explicitly?
(In reply to comment #11) > Markus, are you saying that JDT UI relied on the guidelines, i.e. do you have > public classes that you do not consider subclassable but the Javadoc does not > state that restriction explicitly? No, at a quick glance, I didn't find any problems with classes. But most API methods don't have an explicit statement whether they're intended to be overridden/extended/re-implemented. Up to now, my view was that the cited document sets the default, i.e. methods without explicit comments are not to be overridden. However, I have been told that some projects already didn't follow these rules, so we are in a somewhat undefined state right now. With the advent of API Tooling, it becomes important to have clearly specified rules. We have to decide now how to proceed, otherwise the tooling will lock us into the liberal view (everything allowed if not forbidden) without any chance to escape. And the liberal view contradicts the API document.
In addition to the existing tags (@noextend, ...) it would be nice to have the positive tags (@allowextend, ...). With that the API tooling could create a warning for entities that are not tagged. --> This would force/encourage the developer to make a conscious decision rather than leaving the interpretation up to the API-tooling/guideline/reader
(In reply to comment #13) > In addition to the existing tags (@noextend, ...) it would be nice to have the > positive tags (@allowextend, ...). With that the API tooling could create a > warning for entities that are not tagged. > --> This would force/encourage the developer to make a conscious decision rather > than leaving the interpretation up to the API-tooling/guideline/reader It's been more than a year but API tooling would still benefit from it. +1 for this one.
With the fix for bug 235618 in, we need to decide exactly what the tags mean, how they should be used, their semantics and how they play with the API rules.
This bug hasn't had any activity in quite some time. Maybe the problem got resolved, was a duplicate of something else, or became less pressing for some reason - or maybe it's still relevant but just hasn't been looked at yet. If you have further information on the current state of the bug, please add it. The information can be, for example, that the problem still occurs, that you still want the feature, that more information is needed, or that the bug is (for whatever reason) no longer relevant. -- The automated Eclipse Genie.
