You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@cxf.apache.org by Matthew Glubb <ma...@madebykite.com> on 2011/03/24 13:46:42 UTC

Adding documentation to auto-generated wadl

Hi,

I'm trying to get javadoc documentation added to an auto-generated wadl. Is this possible? Is it possible to document the wadl using annotations instead?

Thanks,


Matt
	

Matthew Glubb
Technical Partner

email: matthew.glubb@madebykite.com
phone: 44 (0) 7715 754017
skype: mglubb

Kite
http://madebykite.com

--
GPG: 96FF DE0E 0B7B 37F0 7F8D C54C E285 3D8F 5625 9244

Re: Adding documentation to auto-generated wadl

Posted by Matthew Glubb <ma...@madebykite.com>.
On 24 Mar 2011, at 13:17, Sergey Beryozkin wrote:

> I was just thinking about it :-)... I'm wondering, would it make sense to
> update the class for the annotation be applicable to parameters as well ?
> Probably yes, what do you think ?

Definitely! :)


Matt


> 
> Cheers, Sergey
> 
> 
> On Thu, Mar 24, 2011 at 1:10 PM, Matthew Glubb <ma...@madebykite.com> wrote:
> 
>> Ah. Brilliant. Thanks Sergey. From that annotation class, it doesn't look
>> like I can document param elements. Is that correct?
>> 
>> 
>> Matt
>> 
>> 
>> Matthew Glubb
>> Technical Partner
>> 
>> email: matthew.glubb@madebykite.com
>> phone: 44 (0) 7715 754017
>> skype: mglubb
>> 
>> Kite
>> http://madebykite.com
>> 
>> --
>> GPG: 96FF DE0E 0B7B 37F0 7F8D C54C E285 3D8F 5625 9244
>> 
>> On 24 Mar 2011, at 12:53, Sergey Beryozkin wrote:
>> 
>>> Hi
>>> 
>>> On Thu, Mar 24, 2011 at 12:46 PM, Matthew Glubb <ma...@madebykite.com>
>> wrote:
>>> 
>>>> Hi,
>>>> 
>>>> I'm trying to get javadoc documentation added to an auto-generated wadl.
>> Is
>>>> this possible? Is it possible to document the wadl using annotations
>>>> instead?
>>>> 
>>>> 
>>> Yes, please check
>>> 
>>> 
>> http://cxf.apache.org/docs/jaxrs-services-description.html#JAXRSServicesDescription-DocumentingresourceclassesandmethodsinWADL
>>> 
>>> Cheers, Sergey
>>> 
>>> 
>>>> Thanks,
>>>> 
>>>> 
>>>> Matt
>>>> 
>>>> 
>>>> Matthew Glubb
>>>> Technical Partner
>>>> 
>>>> email: matthew.glubb@madebykite.com
>>>> phone: 44 (0) 7715 754017
>>>> skype: mglubb
>>>> 
>>>> Kite
>>>> http://madebykite.com
>>>> 
>>>> --
>>>> GPG: 96FF DE0E 0B7B 37F0 7F8D C54C E285 3D8F 5625 9244
>>>> 
>>>> 
>> 
>>

Re: Adding documentation to auto-generated wadl

Posted by Matthew Glubb <ma...@madebykite.com>.
That looks really comprehensive, Sergey. Thanks very much indeed!
	

Matthew Glubb
Technical Partner

email: matthew.glubb@madebykite.com
phone: 44 (0) 7715 754017
skype: mglubb

Kite
http://madebykite.com

--
GPG: 96FF DE0E 0B7B 37F0 7F8D C54C E285 3D8F 5625 9244

On 25 Mar 2011, at 14:06, Sergey Beryozkin wrote:

> Forgot the link to the updated docs:
> 
> https://cwiki.apache.org/confluence/display/CXF20DOC/JAXRS+Services+Description
> 
> Cheers, Sergey
> 
> On Fri, Mar 25, 2011 at 2:05 PM, Sergey Beryozkin <sb...@gmail.com>wrote:
> 
>> Hi
>> 
>> On Thu, Mar 24, 2011 at 1:32 PM, Matthew Glubb <ma...@madebykite.com>wrote:
>> 
>>> On 24 Mar 2011, at 13:17, Sergey Beryozkin wrote:
>>> 
>>>> I was just thinking about it :-)... I'm wondering, would it make sense
>>> to
>>>> update the class for the annotation be applicable to parameters as well
>>> ?
>>>> Probably yes, what do you think ?
>>> 
>>> There is also the issue whereby at the moment one cannot document response
>>> objects. For example:
>>> 
>>> <method name="GET">
>>> <doc>Retrieve object data</doc>
>>> <response status="200">
>>> <doc>Get data about an existing object</doc>
>>> <representation />
>>> </response>
>>> <response status="404">
>>> <doc>Request for object that does not exist </doc>
>>> <representation />
>>> </response>
>>> </method>
>>> 
>>> But this goes to a wider issue that any wadl element can have a doc
>>> element attached and obviously we are limited with what and where we can
>>> annotate.
>>> 
>>> 
>> I've done few modifications for users be able to document response
>> representations, input parameters, WADL request & response elements
>> (wadl:method/wadl:request), using multiple languages if needed. A method
>> level Description annotation can be used to 'target' the response
>> representation, the method itself (default), etc. A Descriptions annotation
>> can group multiple Description annotations, with each one targeting a
>> specific WADL fragment...
>> I have to keep this update on the trunk only as there've been movements in
>> the code base...
>> 
>> Once we start supporting the server-side WADl dev, the docs will be
>> inherited from the input document...
>> 
>> Thanks, Sergey
>> 
>> Matt
>>> 
>>> 
>>> 
>> 
> 
> 
> -- 
> Sergey Beryozkin
> 
> Application Integration Division of Talend <http://www.talend.com>
> http://sberyozkin.blogspot.com

Re: Adding documentation to auto-generated wadl

Posted by Sergey Beryozkin <sb...@gmail.com>.
Forgot the link to the updated docs:

https://cwiki.apache.org/confluence/display/CXF20DOC/JAXRS+Services+Description

Cheers, Sergey

On Fri, Mar 25, 2011 at 2:05 PM, Sergey Beryozkin <sb...@gmail.com>wrote:

> Hi
>
> On Thu, Mar 24, 2011 at 1:32 PM, Matthew Glubb <ma...@madebykite.com>wrote:
>
>> On 24 Mar 2011, at 13:17, Sergey Beryozkin wrote:
>>
>> > I was just thinking about it :-)... I'm wondering, would it make sense
>> to
>> > update the class for the annotation be applicable to parameters as well
>> ?
>> > Probably yes, what do you think ?
>>
>> There is also the issue whereby at the moment one cannot document response
>> objects. For example:
>>
>> <method name="GET">
>> <doc>Retrieve object data</doc>
>> <response status="200">
>> <doc>Get data about an existing object</doc>
>> <representation />
>> </response>
>> <response status="404">
>> <doc>Request for object that does not exist </doc>
>> <representation />
>> </response>
>> </method>
>>
>> But this goes to a wider issue that any wadl element can have a doc
>> element attached and obviously we are limited with what and where we can
>> annotate.
>>
>>
> I've done few modifications for users be able to document response
> representations, input parameters, WADL request & response elements
> (wadl:method/wadl:request), using multiple languages if needed. A method
> level Description annotation can be used to 'target' the response
> representation, the method itself (default), etc. A Descriptions annotation
> can group multiple Description annotations, with each one targeting a
> specific WADL fragment...
> I have to keep this update on the trunk only as there've been movements in
> the code base...
>
> Once we start supporting the server-side WADl dev, the docs will be
> inherited from the input document...
>
> Thanks, Sergey
>
> Matt
>>
>>
>>
>


-- 
Sergey Beryozkin

Application Integration Division of Talend <http://www.talend.com>
http://sberyozkin.blogspot.com

Re: Adding documentation to auto-generated wadl

Posted by Sergey Beryozkin <sb...@gmail.com>.
Hi

On Thu, Mar 24, 2011 at 1:32 PM, Matthew Glubb <ma...@madebykite.com> wrote:

> On 24 Mar 2011, at 13:17, Sergey Beryozkin wrote:
>
> > I was just thinking about it :-)... I'm wondering, would it make sense to
> > update the class for the annotation be applicable to parameters as well ?
> > Probably yes, what do you think ?
>
> There is also the issue whereby at the moment one cannot document response
> objects. For example:
>
> <method name="GET">
> <doc>Retrieve object data</doc>
> <response status="200">
> <doc>Get data about an existing object</doc>
> <representation />
> </response>
> <response status="404">
> <doc>Request for object that does not exist </doc>
> <representation />
> </response>
> </method>
>
> But this goes to a wider issue that any wadl element can have a doc element
> attached and obviously we are limited with what and where we can annotate.
>
>
I've done few modifications for users be able to document response
representations, input parameters, WADL request & response elements
(wadl:method/wadl:request), using multiple languages if needed. A method
level Description annotation can be used to 'target' the response
representation, the method itself (default), etc. A Descriptions annotation
can group multiple Description annotations, with each one targeting a
specific WADL fragment...
I have to keep this update on the trunk only as there've been movements in
the code base...

Once we start supporting the server-side WADl dev, the docs will be
inherited from the input document...

Thanks, Sergey

Matt
>
>
>

Re: Adding documentation to auto-generated wadl

Posted by Matthew Glubb <ma...@madebykite.com>.
On 24 Mar 2011, at 13:17, Sergey Beryozkin wrote:

> I was just thinking about it :-)... I'm wondering, would it make sense to
> update the class for the annotation be applicable to parameters as well ?
> Probably yes, what do you think ?

There is also the issue whereby at the moment one cannot document response objects. For example:

<method name="GET">
<doc>Retrieve object data</doc>
<response status="200">
<doc>Get data about an existing object</doc>
<representation />
</response>
<response status="404">
<doc>Request for object that does not exist </doc>
<representation />
</response>
</method>

But this goes to a wider issue that any wadl element can have a doc element attached and obviously we are limited with what and where we can annotate.

Matt


> 
> Cheers, Sergey
> 
> 
> On Thu, Mar 24, 2011 at 1:10 PM, Matthew Glubb <ma...@madebykite.com> wrote:
> 
>> Ah. Brilliant. Thanks Sergey. From that annotation class, it doesn't look
>> like I can document param elements. Is that correct?
>> 
>> 
>> Matt
>> 
>> 
>> Matthew Glubb
>> Technical Partner
>> 
>> email: matthew.glubb@madebykite.com
>> phone: 44 (0) 7715 754017
>> skype: mglubb
>> 
>> Kite
>> http://madebykite.com
>> 
>> --
>> GPG: 96FF DE0E 0B7B 37F0 7F8D C54C E285 3D8F 5625 9244
>> 
>> On 24 Mar 2011, at 12:53, Sergey Beryozkin wrote:
>> 
>>> Hi
>>> 
>>> On Thu, Mar 24, 2011 at 12:46 PM, Matthew Glubb <ma...@madebykite.com>
>> wrote:
>>> 
>>>> Hi,
>>>> 
>>>> I'm trying to get javadoc documentation added to an auto-generated wadl.
>> Is
>>>> this possible? Is it possible to document the wadl using annotations
>>>> instead?
>>>> 
>>>> 
>>> Yes, please check
>>> 
>>> 
>> http://cxf.apache.org/docs/jaxrs-services-description.html#JAXRSServicesDescription-DocumentingresourceclassesandmethodsinWADL
>>> 
>>> Cheers, Sergey
>>> 
>>> 
>>>> Thanks,
>>>> 
>>>> 
>>>> Matt
>>>> 
>>>> 
>>>> Matthew Glubb
>>>> Technical Partner
>>>> 
>>>> email: matthew.glubb@madebykite.com
>>>> phone: 44 (0) 7715 754017
>>>> skype: mglubb
>>>> 
>>>> Kite
>>>> http://madebykite.com
>>>> 
>>>> --
>>>> GPG: 96FF DE0E 0B7B 37F0 7F8D C54C E285 3D8F 5625 9244
>>>> 
>>>> 
>> 
>>

Re: Adding documentation to auto-generated wadl

Posted by Sergey Beryozkin <sb...@gmail.com>.
Hi Matt,

I was just thinking about it :-)... I'm wondering, would it make sense to
update the class for the annotation be applicable to parameters as well ?
Probably yes, what do you think ?

Cheers, Sergey


On Thu, Mar 24, 2011 at 1:10 PM, Matthew Glubb <ma...@madebykite.com> wrote:

> Ah. Brilliant. Thanks Sergey. From that annotation class, it doesn't look
> like I can document param elements. Is that correct?
>
>
> Matt
>
>
> Matthew Glubb
> Technical Partner
>
> email: matthew.glubb@madebykite.com
> phone: 44 (0) 7715 754017
> skype: mglubb
>
> Kite
> http://madebykite.com
>
> --
> GPG: 96FF DE0E 0B7B 37F0 7F8D C54C E285 3D8F 5625 9244
>
> On 24 Mar 2011, at 12:53, Sergey Beryozkin wrote:
>
> > Hi
> >
> > On Thu, Mar 24, 2011 at 12:46 PM, Matthew Glubb <ma...@madebykite.com>
> wrote:
> >
> >> Hi,
> >>
> >> I'm trying to get javadoc documentation added to an auto-generated wadl.
> Is
> >> this possible? Is it possible to document the wadl using annotations
> >> instead?
> >>
> >>
> > Yes, please check
> >
> >
> http://cxf.apache.org/docs/jaxrs-services-description.html#JAXRSServicesDescription-DocumentingresourceclassesandmethodsinWADL
> >
> > Cheers, Sergey
> >
> >
> >> Thanks,
> >>
> >>
> >> Matt
> >>
> >>
> >> Matthew Glubb
> >> Technical Partner
> >>
> >> email: matthew.glubb@madebykite.com
> >> phone: 44 (0) 7715 754017
> >> skype: mglubb
> >>
> >> Kite
> >> http://madebykite.com
> >>
> >> --
> >> GPG: 96FF DE0E 0B7B 37F0 7F8D C54C E285 3D8F 5625 9244
> >>
> >>
>
>

Re: Adding documentation to auto-generated wadl

Posted by Matthew Glubb <ma...@madebykite.com>.
Ah. Brilliant. Thanks Sergey. From that annotation class, it doesn't look like I can document param elements. Is that correct?


Matt
	

Matthew Glubb
Technical Partner

email: matthew.glubb@madebykite.com
phone: 44 (0) 7715 754017
skype: mglubb

Kite
http://madebykite.com

--
GPG: 96FF DE0E 0B7B 37F0 7F8D C54C E285 3D8F 5625 9244

On 24 Mar 2011, at 12:53, Sergey Beryozkin wrote:

> Hi
> 
> On Thu, Mar 24, 2011 at 12:46 PM, Matthew Glubb <ma...@madebykite.com> wrote:
> 
>> Hi,
>> 
>> I'm trying to get javadoc documentation added to an auto-generated wadl. Is
>> this possible? Is it possible to document the wadl using annotations
>> instead?
>> 
>> 
> Yes, please check
> 
> http://cxf.apache.org/docs/jaxrs-services-description.html#JAXRSServicesDescription-DocumentingresourceclassesandmethodsinWADL
> 
> Cheers, Sergey
> 
> 
>> Thanks,
>> 
>> 
>> Matt
>> 
>> 
>> Matthew Glubb
>> Technical Partner
>> 
>> email: matthew.glubb@madebykite.com
>> phone: 44 (0) 7715 754017
>> skype: mglubb
>> 
>> Kite
>> http://madebykite.com
>> 
>> --
>> GPG: 96FF DE0E 0B7B 37F0 7F8D C54C E285 3D8F 5625 9244
>> 
>>

Re: Adding documentation to auto-generated wadl

Posted by Sergey Beryozkin <sb...@gmail.com>.
Hi

On Thu, Mar 24, 2011 at 12:46 PM, Matthew Glubb <ma...@madebykite.com> wrote:

> Hi,
>
> I'm trying to get javadoc documentation added to an auto-generated wadl. Is
> this possible? Is it possible to document the wadl using annotations
> instead?
>
>
Yes, please check

http://cxf.apache.org/docs/jaxrs-services-description.html#JAXRSServicesDescription-DocumentingresourceclassesandmethodsinWADL

Cheers, Sergey


> Thanks,
>
>
> Matt
>
>
> Matthew Glubb
> Technical Partner
>
> email: matthew.glubb@madebykite.com
> phone: 44 (0) 7715 754017
> skype: mglubb
>
> Kite
> http://madebykite.com
>
> --
> GPG: 96FF DE0E 0B7B 37F0 7F8D C54C E285 3D8F 5625 9244
>
>