Each of these pages has only a short description that says, for example:
LzAudio is a shortcut for LzAudioService. Use lz.Audio instead.
where LzAudioServive is a link to that page.
On Jun 5, 2008, at 1:49 PM, P T Withington wrote:
I guess that will work, but I suppose you should also insert some
English saying that the entry is deprecated, since the keyword will
do nothing.
I think the people who were writing @deprecated were hoping that it
would do something like what [this](http://java.sun.com/j2se/1.5.0/
docs/api/java/lang/Deprecated.html) does:
What happens when an API is Deprecated
[...]
JavaDoc also pays special attention to @deprecated tags when
generating html files. Javadoc parses the entire paragraph
following the @deprecated tag and moves it to the front of the
description, placing it in italics and preceding it with a
warning, "Note: foo is deprecated", in bold. It also adds
"Deprecated" in bold to any index entries mentioning the
deprecated entity.
[How and When to Deprecate APIs](http://java.sun.com/j2se/1.4.2/
docs/guide/misc/deprecation/deprecation.html)
On 2008-06-04, at 18:03 EDT, Lou Iorio wrote:
so should I just do this for now:
* @keywords deprecated
so @deprecated doesn't show up in the html, and we
(meaning someone smarter than I) can fix it later?
On Jun 4, 2008, at 4:48 PM, David Temkin wrote:
The word "deprecated", without the "@", is for public
consumption, along with an explanation as below.
On Jun 4, 2008, at 1:16 PM, Lou Iorio wrote:
I'm not entirely sure, but I believe it ignores it.
I was not sure if "deprecated" was for public consumption, or
just a
way of commenting the source. In other places I've seen it, a
class or
method is also marked "private", so that doesn't show up in the
doc.
The files in question are all in trunk/WEB-INF/lps/lfc/services,
and all contain
the text "xxx is a shortcut for newxxx, for example:
LzAudio is a shortcut for LzAudioService. Use lz.Audio instead.
where LzAudioService is a link to that page.
On Jun 4, 2008, at 4:03 PM, P T Withington wrote:
It eliminates it from the html output, but does it somehow also
signal that the API being documented is deprecated? I.e., does
the doc tool do something with the keyword, or just ignore it?
---
As a future improvement, it might be nice to have an
@deprecated that was something like:
@deprecated [release version when deprecated] [what to use
instead]
but for now, the keyword option is sufficient.
On 2008-06-04, at 15:45 EDT, Lou Iorio wrote:
Changing
* @deprecated
to
* @keywords deprecated
in the lzs source does indeed eliminate the @deprecated in the
html output.
Is this the behavior we want? If so, I'll make this change the
singleton doc.
Lou
