classpath
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: since, status and specnote tags


From: Robert Schuster
Subject: Re: since, status and specnote tags
Date: Wed, 12 Jan 2005 02:11:15 +0100
User-agent: Mozilla/5.0 (X11; U; Linux i686; de-AT; rv:1.7.5) Gecko/20050107

Hi again.

Michael Koch wrote:
Am Mittwoch, 12. Januar 2005 00:28 schrieb Robert Schuster:
  
Hi,
what is our policy regarding the since, status and specnote tags? I
have seen @status entries being replaced by @specnote and thought
they should not be used any more but then I found them again in
newer classes. That leads my to following questions:

What should @specnote or @status describe?
    

@specnote explain when the API or the semantics changed from earlier 
version of JDK, e.g. a protected method became public in a newer 
version of the JDK.

  

We don't really use the @status tag. In some classes it describes what 
JDK the class is compatible too.

  
This what I thought about them too when I had seen them the first time.
I feel a bit bad about not knowing whether I should use this tag or not. Can we have an agreement on this?


  
Is any of them considered deprecated and should be replaced by the
other whenever seen?
    

No, they have different meanings as we use them.

  
Regarding the @since tag: Should we strive to version every class
and method?
    

We only need to add this tag when the JDK docs has a "Since: " entry.
  
That means adding it to other symbols too is not forbidden but not encouraged ... makes me unhappy as well
and a general policy would help.

Please do not misunderstand me: I would love too see an agreement that says

You should add @someTag whenever bla foo baz.

But this does not mean 'You must add @ ...'.

Anyone else feeling better if could reduce the vagueness of these tags?

cu
Robert

reply via email to

[Prev in Thread] Current Thread [Next in Thread]