Community
Participate
Working Groups
I20060512-1600 The component.xml file was changed (see diff between revisions 1.7 and 1.5) to reflect that usage restrictions (like 'cannot be subclassed') were not specified in the Javadoc of some types. However these restrictions should be specified in the Javadoc to clarify what a client can expect to do with the type.
Created attachment 41556 [details] Proposed patch
To be clear, we are not changing anything, except clarifying the doc about assumptions which were not mentionned, though present in the component.xml. Mcq - pls cast your vote.
Darin - pls vote
Dani - pls vote
+1 for 3.2RC5
The attached patch does more, e.g. it adds new constants for IClasspathAttribute to the component.xml and the Javadoc. Note that personally I think that more clients rely on the existing Javadoc than the component.xml contents, therefore I'd rather adjust the component.xml to the Javadoc than the other way around.
Sorry I wasn't clear. The idea was to revert the changes made to the component.xml in RC4, and then clarify the corresponding Javadoc.
From discussion with Dani, there are 2 parts in this issue: 1. revert the component.xml to its previous state (stricter) 2. align the javadoc on component.xml We could handle these separately, arguing (1) is needed for 3.2, and doc clarification (2) is for 3.3; since it could be perceived as an API change (though it is strictly only acknowledging the reality from both implementation and component.xml). Ping'ing Jim for his take on API issue (2).
The question is whether code, Javadoc or component.xml wins. This isn't clear. Regarding the API rules of engagement in Eclipse (see http://www.eclipse.org/articles/Article-API%20use/eclipse-api-usage-rules.html) I think the Javadoc should normally win or we should clarify those documents and mention the component.xml as well.
Personally, my view is that if we believe that the code is currently working properly and we don't intend to change that behavior, but it's behavior differs from the javadoc, then the javadoc is wrong. Fixing this is not really even a breaking change, since no consumer could be depending on the stated behavior (since it differs from what the code actually does).
I fully agree with comment 10
> Fixing this is not really even a breaking change, Yes, I agree on that one. But look at this example: - let's say release 1 specs 'null' is allowed - we find out it should not be allowed and change the Javadoc for release 2 ==> no code change clients will work as before - some coder now explicitly adds an assert in release 3 in order to fulfill the Javadoc ==> client might now be broken Don't get me wrong I also think cleaning these things up is a good thing. I just wouldn't do it in RC5 and be conservative here.
Unless these are considered as API changes, I see no reason not to do these, as standard late doc work.
I believe the javadoc should be cleaned up to reflect the 'reality' of the implementation. If there was no way a client could have implemented the interfaces which now explicitly state 'not intended to be implemented by clients', then adding the clarification is the right thing to do. Similarly, if there was not way a client could have subclassed the classes now marked as 'not intended to be instantiated or subclassed by clients', then adding the clarification is the right thing to do. I beleive you should also post this to your mailing list, so clients are not surprised by the change (though, I doubt they will be). However, if it was possible for a client to implement or subclass the changed types, then this change should be delayed for 3.3.
Martin - what is your opinion ? Darin - we are not changing any existing contract, simply clarifying the current story.
+1
Hmm, not so easy. In my opinion Javadoc is king. I see component.xml just as derived from Javadoc to help with tool support. I think there are 3 cases: a.) Implemententing ITerminalSymbols or extending DefaultCodeFormatterConstants is possible, but there is no real use or harm when doing that. b.) It is not possible to extend 'AST': it has a private constructor, CharOperation, CompletionProposal and CompletionContext: they are final c.) some clients may have implemented IScanner, ITypeParameter, IClasspathAttribute or extended InvalidInputException and even found a use for that. Making the Javadoc stricter would IMO be an API change. I think it would require the full API approval path/process for that. I don't think a.) is worth that. c.) maybe, but I would rather wait for 3.3. b.) is ok to fix, but not really benefitial to the user.
Actually, Kevin just pointed me at the API guidelines, which are actually saying that by default, APIs are not extensible, unless said explicitly. So our current javadoc is fine; and only for consistency purpose do we need to align it on other places where we explicitly tell about not being subclassable. http://www.eclipse.org/articles/Article-API%20use/eclipse-api-usage-rules.html Instantiating platform API classes Not all concrete API classes are intended to be instantiated by just anyone. API classes have an instantiation contract indicating the terms under which instances may be created. The contract may also cover things like residual initialization responsibilities (for example, configuring a certain property before the instance is fully active) and associated lifecycle responsibilities (for example, calling dispose() to free up OS resources hung on to by the instance). Classes that are designed to be instantiated by clients are explicitly flagged in the Javadoc class comment (with words like "Clients may instantiate."). * Restricted instantiators. Do not instantiate an API class that is documented as available only to certain parties unless you're one of them. In some situations, classes need to be part of the public API for the benefit of a certain party (often internal); instantiating one of these classes incorrectly has unspecified (and perhaps unpredictable) consequences. Subclassing platform API classes Only a subset of the API classes were designed to be subclassed. API classes have a subclass contract indicating the terms under which subclasses may be declared. This contract also covers initialization responsibilities and lifecycle responsibilities. Classes that are designed to be subclassed by clients are explicitly flagged in the Javadoc class comment (with words like "Clients may subclass."). * Restricted subclassers. Do not subclass an API class that is not intended to be subclassed. Treat these classes as if they had been declared final. (These are sometimes referred to as "soft final" classes).
So this really is a doc clarification issue.
I forgot about that. +1 then for the patch from comment 1.
Released patch from comment 1 to HEAD.
Verified with I20060519-0010 for 3.2RC5
