On Apr 30, 2008, at 7:47 AM, Seth Call wrote:
> Alright. I'll prototype it and poke my head back up when I get
> something working.
>
Great !
Marc.
>
> On Wed, Apr 30, 2008 at 6:29 AM, Marc Hadley <Marc.Hadley_at_sun.com>
> wrote:
>> On Apr 29, 2008, at 10:56 PM, Seth Call wrote:
>>
>>
>>> Let me propose an alternate solution... see what you all think:
>>>
>>> Say instead that something like the previously attached
>>> javadoc-containing XML file was deployed with a Jersey instance.
>>> Say
>>> it always lives in a known 'resource' directory of some sort.
>>>
>>> The current dynamic WADL generating code could be altered to look
>>> for
>>> the presence of this XML resource file; if it finds it, it could
>>> XPath
>>> into it to extract out the relevant Javadoc bits for
>>> resources/requests etc.
>>>
>>> I like this because there remains one way to get your WADL, and this
>>> feature is clearly more incremental in nature.
>>>
>>> Anyone else favor this as much as I do? This sounds ideal to me,
>>> but
>>> admittedly I don't have the big picture here.
>>>
>>>
>> That sounds like a good approach to me. I had in mind something
>> similar
>> using a pre-built WADL directly rather than an intermediate XML
>> format but
>> either works I think.
>>
>> Marc.
>>
>>
>>
>>
>>>
>>> On Tue, Apr 29, 2008 at 9:09 PM, Seth Call <sethcall_at_gmail.com>
>>> wrote:
>>>
>>>> Using the Bookstore Jersey 0.7 example as source to test on, the
>>>> XML
>>>> doclet I wrote generates the attached XML (just so an example can
>>>> be
>>>> seen).
>>>>
>>>> In short, it's all the javadoc data, along with
>>>> class/method/interface/annotation information. I believe a WADL
>>>> could be generated directly from this XML, using just XSLT.
>>>>
>>>> But I was hoping to get just a little bit of guidance, because
>>>> making
>>>> a new doclet (instead of using this existing XML doclet w/ XSLT)
>>>> would
>>>> allow one to *feasibly* reuse code within jersey that does the
>>>> dynamic
>>>> WADL generation, so that one could make changes to WADL generation
>>>> code in one place and have it take affect in both the dynamic piece
>>>> and the doclet piece. The question is such a common factoring
>>>> realistic.
>>>>
>>>> So, I tried to find the code that does the dynamic generation,
>>>> and I
>>>> believe the bulk of it is in:
>>>>
>>>> jersey/src/impl/com/sun/ws/rest/impl/WadlGenerator.java
>>>>
>>>> From what I can tell, it would be very hard to somehow use this
>>>> code
>>>> within the context of a doclet, since it seems quite tied to
>>>> running
>>>> within the context of the jersey runtime. Does anyone else have
>>>> a gut
>>>> feel on this?
>>>>
>>>> I'm still interested in trying to generate the WADL from a
>>>> doclet, and
>>>> I believe I will start doing just that. So if anyone thinks it's
>>>> wrong to use the XML Doclet /XSLT, then let me know. Otherwise
>>>> I'll
>>>> take a serious stab at it and ping back here when I make progress.
>>>>
>>>> Regards,
>>>> Seth
>>>>
>>>>
>>>>
>>>> On Tue, Apr 29, 2008 at 10:46 AM, Seth Call <sethcall_at_gmail.com>
>>>> wrote:
>>>>
>>>>> Hi Marc,
>>>>>
>>>>> I see. I had in mind that there would be a new annotation (or
>>>>> param
>>>>> on existing annotations) that let you document these elements,
>>>>> but I
>>>>> can appreciate that Javadoc would be
>>>>>
>>>>> 1) more intuitive/less learning curve
>>>>> 2) more readable compared to an inline string.
>>>>>
>>>>> Funny thing is, I just open-sourced a doclet that generates an XML
>>>>> representation of the data in Javadoc on google code. I'm
>>>>> thinking one
>>>>> could use XSLT/XPATH on the output of this doclet, and create
>>>>> the WADL
>>>>> from it. Are there any red flags with using this XML-
>>>>> generating,
>>>>> maven-based, Apache 2.0 licensed project hosted on google code
>>>>> to help
>>>>> accomplish this? Or would there be a reason that this must be a
>>>>> new
>>>>> doclet sourced directly with Jersey?
>>>>>
>>>>> I don't have a good feel for the size of this task, but I am very
>>>>> interested. I'd like to look through the Jersey source a little
>>>>> tonight to get a better feel...
>>>>>
>>>>> Thanks,
>>>>> Seth
>>>>>
>>>>>
>>>>>
>>>>> On Tue, Apr 29, 2008 at 10:18 AM, Marc Hadley
>>>>> <Marc.Hadley_at_sun.com>
>> wrote:
>>>>>
>>>>>> This is one of those tasks that we've discussed but haven't had
>>>>>> the
>> time to
>>>>>> implement yet. We discussed implementing a doclet that would
>> generate a WADL
>>>>>> from the Javadoc in resource classes. One issue with this is that
>> this would
>>>>>> require a compile-time step rather than the current all-runtime
>>>>>> WADL
>> support
>>>>>> but I think that it would be possible to allow the runtime
>> /application.wadl
>>>>>> to be overridden with a pre-generated file that contains
>> documentation.
>>>>>>
>>>>>> Any volunteers to help with creating such a doclet ?
>>>>>>
>>>>>> Marc.
>>>>>>
>>>>>>
>>>>>>
>>>>>> On Apr 29, 2008, at 11:04 AM, Seth Call wrote:
>>>>>>
>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> I'm trying out Jersey and something stands out... I don't see a
>> way
>>>>>>> that someone can cause text to emit into the WADL 'doc' element,
>> which
>>>>>>> is available on most elements in WADL (such as request,
>>>>>>> resource,
>>>>>>> resources, etc).
>>>>>>>
>>>>>>> Am I missing something?
>>>>>>>
>>>>>>> I think the value here is obvious, but I'll state it anyway just
>> in case:
>>>>>>>
>>>>>>> Giving a way to allow developers to document the individual
>> elements
>>>>>>> of an interface, in the structure that those elements occur,
>> greatly
>>>>>>> lowers the bar for creating documentation. Javadoc is probably
>> the
>>>>>>> best example.
>>>>>>> Specific to Jersey and WADLs, one can then easily process the
>>>>>>> XML
>>>>>>> using XSLT or XPATH and generate quality documentation.
>>>>>>>
>>>>>>> The 'doc' element can be seen in the WADL specification:
>>>>>>> https://wadl.dev.java.net/wadl20061109.pdf. p21-29 for RelaxNG
>> or
>>>>>>> XSD definitions.
>>>>>>>
>>>>>>> So anyway, if there isn't a way to do this today, is the next
>>>>>>> step
>> for
>>>>>>> me to open an enhancement request in the tracker?
>>>>>>>
>>>>>>> Seth
>>>>>>>
>>>>>>>
>> ---------------------------------------------------------------------
>>>>>>> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>>>>>>> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>
>>>>>> ---
>>>>>> Marc Hadley <marc.hadley at sun.com>
>>>>>> CTO Office, Sun Microsystems.
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>> ---------------------------------------------------------------------
>>>>>> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>>>>>> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>>>>>>
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> The poor have to labour in the face of the majestic equality of
>>>>> the
>>>>> law, which forbids the rich as well as the poor to sleep under
>>>>> bridges, to beg in the streets, and to steal bread.
>>>>>
>>>>>
>>>>
>>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>>> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>>>
>>>
>>
>> ---
>> Marc Hadley <marc.hadley at sun.com>
>> CTO Office, Sun Microsystems.
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>>
>>
>
>
>
> --
> The poor have to labour in the face of the majestic equality of the
> law, which forbids the rich as well as the poor to sleep under
> bridges, to beg in the streets, and to steal bread.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>
---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.