users@jersey.java.net

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

From: Martin Grotzke <martin.grotzke_at_freiheit.com>
Date: Fri, 13 Mar 2009 16:05:52 +0100

On Wed, 2009-03-11 at 10:08 +0100, Paul Sandoz wrote:
> 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?
For me this is the case: most important information comes from class,
method and param docs.

Cheers,
Martin


>
> 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
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
> For additional commands, e-mail: users-help_at_jersey.dev.java.net