users@jersey.java.net

Re: [Jersey] Documentation of resource via javadoc or annotations [WAS: Re: [wikis.sun.com] Jersey > WADL]

From: Paul Sandoz <Paul.Sandoz_at_Sun.COM>
Date: Wed, 11 Mar 2009 10:08:30 +0100

Hi,

I am not hugely informed on this matter, but i suspect it may be
better to keep closer to the JavaDoc if the common case is that one
will want to use JavaDoc + the tags. Is that the most likely scenario?

Paul.


On Mar 5, 2009, at 9:33 AM, Martin Grotzke wrote:

> Hi,
>
> taking this from the wiki to this list...
>
> On Wed, 2009-03-04 at 14:37 -0800, wikis-no-reply_at_sun.com wrote:
>> WADL
>> Page commented by cpiggott
>>
>> I wonder whether or not it would be better to use annotations rather
>> than special javadoc tags. You could then let the jersey runtime
>> store things like the return representations for each HTTP status.
>> It
>> could collect all of this information at the same time it is
>> collecting the other annotations. To me that seems like it would be
>> cleaner, and would aid the build process for new-to-jersey
>> developers.
>> The expense is that the classes would grow a little, but not by very
>> much.
> When I started with extended wadl I also thought about this and
> decided
> not to mix up runtime/application logic with information that is only
> relevant for documentation - therefore the separation of java code
> (with
> annotations) and javadoc. I thought it might be confusing if there are
> annotations where some annotations are relevant for the application
> behaviour and some annotations are relevant for documentation.
>
> What I also see, is that there's lots of javadoc stuff for that
> documentation, but this would not really change when moving from
> javadoc
> to annotations, as the information has to be stored somewhere.
>
> Any thoughts?
>
> Cheers,
> Martin
>
>
>>
>> Possible?
>>
>>
>> Change Notification Preferences
>> View Online | Reply To This