[Laszlo-dev] @deprecated

[P T Withington]

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
>>>>
>>>
>>
>