Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 406706

Summary:	API with @noreference needs class comment
Product:	[Eclipse Project] Platform	Reporter:	John Arthorne <john.arthorne>
Component:	UI	Assignee:	Michael Rennie <Michael_Rennie>
Status:	VERIFIED FIXED	QA Contact:
Severity:	normal
Priority:	P3	CC:	daniel.rolka, Michael_Rennie, pwebster
Version:	4.3	Flags:	pwebster: review+
Target Milestone:	4.3 RC1
Hardware:	PC
OS:	Windows 7
Whiteboard:
Bug Depends on:
Bug Blocks:	403190

Description John Arthorne

2013-04-26 17:07:22 EDT

Javadoc generation doesn't support @noreference tag on classes. As a result, all of our @noreference classes/interfaces have no indication in the javadoc that they should not be used. I think we should add an English sentence in the class javadoc to make it crystal clear that these types are off limits. Something like this:

* This [class|interface] must not be referenced by clients. 
* This API may be deleted in a future release
* @noreference

Comment 1 John Arthorne

2013-04-26 17:08:10 EDT

Mike correct me if I'm wrong and there is some way to do this in javadoc generation step.

Comment 2 Michael Rennie

2013-04-29 10:28:18 EDT

(In reply to comment #1)
> Mike correct me if I'm wrong and there is some way to do this in javadoc
> generation step.

If you use auto-completion to add the tag it looks like the following (where the 'class' part changes depending on what kind of member the tag is on - class, interface, enum, method, field, etc):

'@noreference This class is not intended to be referenced by clients'

As for during the generation step, I have no idea how that works, but I have opened a bug for it: bug 403245

Comment 3 Paul Webster

2013-05-06 08:10:36 EDT

So do we need to go back and find @noreferences that don't have the tagline?

PW

Comment 4 Michael Rennie

2013-05-07 10:29:36 EDT

Pushed changes to https://git.eclipse.org/r/12581

This includes the updated class comments and updates to the generation stuff

Comment 5 Paul Webster

2013-05-15 11:44:18 EDT

Released with http://git.eclipse.org/c/platform/eclipse.platform.ui.git/commit/?id=8cc5a361955d563dc4a90d6be58efce386e01779

PW

Comment 6 Daniel Rolka

2013-05-20 07:43:56 EDT

Verified in the build: I20130516-2200