users@jersey.java.net

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

From: Martin Grotzke <martin.grotzke_at_freiheit.com>
Date: Thu, 05 Mar 2009 16:44:44 +0100

On Thu, 2009-03-05 at 08:30 -0700, Andrew Ochsner wrote:
> I would tend to agree with you. Having annotations for things that
> are strictly documentation seems a bit odd to me. Feels like that's
> more of what javadoc's purpose is. The problem we run into is that we
> know the documentation and the code will get out of sync so the more
> information we can grab from reflection & annotations needed by the
> runtime, the better we'll be.
That's right, but it's not a point for an annotation that replaces a
javadoc tag, as long as this annotation is not *really* used during
runtime (by jersey). Such an annotation used for documentation only can
run out of synch without any difference.

Cheers,
Martin


>
> On Thu, Mar 5, 2009 at 5:58 AM, Christopher Piggott
> <cpiggott_at_gmail.com> wrote:
> Hi,
>
> Martin Grotzke wrote:
> >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
>
>
> That crossed my mind, but isn't there a case where it would be
> useful
> to know at run-time? Suppose for instance a client asks for
> something
> as an application/something+xml but I can't fullfill the
> request.
> Instead, I am going to return say an HTTP 500, and an object
> that's
> actually an application/some_error+xml. Would there be any
> advantage
> to the runtime knowing that I intend to do this?
>
> --Chris
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
> For additional commands, e-mail:
> users-help_at_jersey.dev.java.net
>