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.