So, if the doctools are not going to do it for us (because they ignore
@keywords deprecated and don't implement @deprecated), I think we need
to change the English to say:
LzAudio is deprecated. You should update your code to use lz.Audio
instead.
And have lz.Audio a link to the (hypothetical) Services page, that
lists all the service singletons (Audio, Cursor, etc.). Each of those
singletons should, in turn, link to the corresponding service class
that they are the single instantiation of. (I.e., lz.Audio is the
only instance of the LzAudioService class. You have to read the
LzAudioService class description to find the capabilities of lz.Audio,
and you use lz.Audio to access those capabilities.)
Sorry for being a pedant.
On 2008-06-05, at 13:55 EDT, Lou Iorio wrote:
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
