Unclean Code / Bad Documentation

Typically, the eclipse platform is good about keeping their code clean, and documented for adopters that may need to use the API they provide. However, even the platform teams slips up everyonce in a while.

Today while working on some code that uses the TemplateProposals class, I ran across this code when debugging:

/*
 * @see ICompletionProposal#apply(IDocument)
 */
public final void apply(IDocument document) {
   // not called anymore
}

/*
 * @see org.eclipse.jface.text.contentassist.ICompletionProposalExtension#apply(org.eclipse.jface.text.IDocument, char, int)
 */
public void apply(IDocument document, char trigger, int offset) {
  // not called any longer
}

The methods above probably should be marked with the @deprecated annotation, or at least made to work by calling the appropriate new methods that they replaced. It would help adopters avoid using the class, or at least update the javadoc so that it doesn't get called at all. Not sure how long this has been in there, but it's the type of thing that can drive an adopter nuts trying to figure out why something isn't working as expected.