How to specify that a method is Deprecated

[Sree]

We have a set of methods that should no longer be used. But since they are
public methods and have already been used, across many systems, we cannot
change the interface but would like to specify that they are deprecated methods,
so that they will not be used in future. How do we specify that a method
is Deprecated?

[Paul Clapham]

You use the "@deprecated" tag in the Javadoc comments before the methods.
Here's an excerpt from the Javadoc documentation (which I found in my
downloaded version of the SDK in directory C:\jdk1.3\docs\tooldocs\javadoc):

[start quote]
@deprecated deprecated-text
Adds a comment indicating that this API should no longer be used (even
though it may continue to work). Javadoc moves the deprecated-text ahead of
the description, placing it in italics and preceding it with a bold warning:
"Deprecated".
The first sentence of deprecated-text should at least tell the user when the
API was deprecated and what to use as a replacement. Javadoc copies just the
first sentence to the summary section and index. Subsequent sentences can
also explain why it has been deprecated. You should include a {@link} tag
(for Javadoc 1.2 or later) that points to the replacement API:


a.. For Javadoc 1.2 and later, use a {@link} tag. This creates the link
in-line, where you want it. For example:
/**
* @deprecated As of JDK 1.1, replaced by {@link
#setBounds(int,int,int,int)}
*/

b.. For Javadoc 1.1, the standard format is to create a @see tag (which
cannot be in-line) for each @deprecated tag. "Sree"
<pssreeprasad@hotmail.com> wrote in message news:3aec59e8$1@news.devx.com...
>
> We have a set of methods that should no longer be used. But since they are
> public methods and have already been used, across many systems, we cannot
> change the interface but would like to specify that they are deprecated
methods,
> so that they will not be used in future. How do we specify that a method
> is Deprecated?

[Paul Clapham]

You use the "@deprecated" tag in your Javadoc comments before those methods.
Here's an excerpt from the Javadoc documentation (which I found in my
downloaded version of the SDK at C:\jdk1.3\docs\tooldocs\javadoc):

[start quote]
@deprecated deprecated-text
Adds a comment indicating that this API should no longer be used (even
though it may continue to work). Javadoc moves the deprecated-text ahead of
the description, placing it in italics and preceding it with a bold warning:
"Deprecated".
The first sentence of deprecated-text should at least tell the user when the
API was deprecated and what to use as a replacement. Javadoc copies just the
first sentence to the summary section and index. Subsequent sentences can
also explain why it has been deprecated. You should include a {@link} tag
(for Javadoc 1.2 or later) that points to the replacement API:


a.. For Javadoc 1.2 and later, use a {@link} tag. This creates the link
in-line, where you want it. For example:
/**
* @deprecated As of JDK 1.1, replaced by {@link
#setBounds(int,int,int,int)}
*/

b.. For Javadoc 1.1, the standard format is to create a @see tag (which
cannot be in-line) for each @deprecated tag.
[end quote]

PC2

"Sree" <pssreeprasad@hotmail.com> wrote in message
news:3aec59e8$1@news.devx.com...
>
> We have a set of methods that should no longer be used. But since they are
> public methods and have already been used, across many systems, we cannot
> change the interface but would like to specify that they are deprecated
methods,
> so that they will not be used in future. How do we specify that a method
> is Deprecated?