[Laszlo-dev] @deprecated

[Lou Iorio]

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