Re: since, status and specnote tags

Tue, 11 Jan 2005 17:33:14 -0800

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




_______________________________________________
Classpath mailing list
[email protected]
http://lists.gnu.org/mailman/listinfo/classpath






















					Reply via email to