The issue has been resolved by debugging the ResourceDoclet code. No
<paramDoc> element was being generated because I had a mismatch between
the number methodParams and @param tags. In such case the ResourceDoclet
was silently ignoring the paramDoc generation. I have created an issue at:
http://java.net/jira/browse/JERSEY-1732
The issue includes a simple and safe patch to emit a warning in such cases.
On 02/13/2013 10:41 AM, Farrukh Najmi wrote:
>
>
> (Copying Martin Grotzke as his name is in the relevant code hoping he
> could help)
>
> I am rephrasing my question in an attempt to make it a simpler
> question for people to answer.
>
> If my situation is:
>
> * My jersey rest endpoint project uses JAXB generated classes from a
> dependency project
> * I have no need for any custom tag handling
> * I want to generate
> o *<paramDoc> elements *in target/classes/resourcedoc.xml
> o *<doc> elements* in target/classes/application.wadl for
> QueryParams in my GET resource method
>
> Then what do I need to do to adapt the "Generate WADL - Jersey Sample"
> to my project?
>
> Specifically:
>
> * Do I need anything similar to the
> com.sun.jersey.samples.generatewadl.util and its
> ExampleWadlGenerator and ExampleDocProcessor
> * How does it impact my configuration for maven-javadoc-plugin?
> o What do I need to specify so that *<paramDoc> elements *are
> generated in target/classes/resourcedoc.xml for @param
> javadoc tags describing my QueryParams*
> *
> o Do I need to specify -processors in additionalparam?
>
> <additionalparam>-output
> ${project.build.outputDirectory}/resourcedoc.xml *-processors
> com.sun.jersey.samples.generatewadl.util.ExampleDocProcessor*</additionalparam>
>
> * How does it impact my configuration for maven-wadl-plugin
> o What do I need to specify in <wadlGeneratorDescription>to
> process *<paramDoc> elements *in the
> target/classes/resourcedoc.xml in *<doc> elements* in
> target/classes/application.wadl?
>
> Thanks for any help from any one on the list on this.
>
>
> On 02/13/2013 09:43 AM, Farrukh Najmi wrote:
>>
>> Hi Guys,
>>
>> Here is some more info on the problem. I believe the problem is in
>> the mavan-javadoc-plugin execution as it produces a
>> target/classes/resourcedoc.xml that does not have the javadoc
>> comments for method parameters. Though there is a lot in this post
>> please *focus on the text that is in bold*.
>>
>> Here is the source code fragment for a search method:
>>
>> /**
>> * Executes a parameterized query.
>> * In addition to the standard parameters below their may be any
>> number of query-specific parameters.
>> * Such parameterized are defined by the query specification.
>> *
>> * @param queryId the id of the query being executed
>> *
>> *
>> * @response.representation.200.qname
>> {urn:oasis:names:tc:ebxml-regrep:xsd:query:4.0}QueryResponse
>> * @response.representation.200.mediaType application/xml
>> *
>> * @return the response to the query. Format of response is
>> controlled by the format parameter
>> */
>> @Path("/search")
>> @GET
>> @Produces({"application/xml","application/json",
>> MediaType.TEXT_HTML})
>> public Response search(
>> @QueryParam("queryId") String queryId
>> ) throws JAXBException {...}
>>
>> Here is the target/classes/resourcedoc.xml produced by
>> javadoc:javadoc goal of maven-javadoc-plugin.
>> *Notice that the @param queryId did not generate a corresponding
>> <paramDoc> element*
>>
>> ...
>> <methodDocs>
>> <methodDoc>
>> <methodName>search</methodName>
>> <commentText><![CDATA[Executes a parameterized query.
>> In addition to the standard parameters below their may be any number
>> of query-specific parameters.
>> Such parameterized are defined by the query specification.]]>
>> </commentText>
>> <responseDoc>
>> <returnDoc>the response to the query. Format
>> of response is controlled by the format parameter</returnDoc>
>> <representations>
>> <representation
>> element="ns2:QueryResponse" status="200"
>> mediaType="application/xml"
>> xmlns:ns2="urn:oasis:names:tc:ebxml-regrep:xsd:query:4.0"/>
>> </representations>
>> </responseDoc>
>> </methodDoc>
>> ...
>> <methodDocs>
>> ...
>>
>> Here is the output from javadoc:javadoc which has some warning that
>> is likely not relevant because I see it in the "Generate WADL -
>> Jersey Sample" which produces expected <paramDocs>.
>>
>> [javadoc:javadoc]
>> Setting property: classpath.resource.loader.class =>
>> 'org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader'.
>> Setting property: velocimacro.messages.on => 'false'.
>> Setting property: resource.loader => 'classpath'.
>> Setting property: resource.manager.logwhenfound => 'false'.
>> **************************************************************
>> Starting Jakarta Velocity v1.4
>> RuntimeInstance initializing.
>> Default Properties File:
>> org/apache/velocity/runtime/defaults/velocity.properties
>> Default ResourceManager initializing. (class
>> org.apache.velocity.runtime.resource.ResourceManagerImpl)
>> Resource Loader Instantiated:
>> org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader
>> ClasspathResourceLoader : initialization starting.
>> ClasspathResourceLoader : initialization complete.
>> ResourceCache : initialized. (class
>> org.apache.velocity.runtime.resource.ResourceCacheImpl)
>> Default ResourceManager initialization complete.
>> Loaded System Directive: org.apache.velocity.runtime.directive.Literal
>> Loaded System Directive: org.apache.velocity.runtime.directive.Macro
>> Loaded System Directive: org.apache.velocity.runtime.directive.Parse
>> Loaded System Directive: org.apache.velocity.runtime.directive.Include
>> Loaded System Directive: org.apache.velocity.runtime.directive.Foreach
>> Created: 20 parsers.
>> Velocimacro : initialization starting.
>> Velocimacro : adding VMs from VM library template : VM_global_library.vm
>> *ResourceManager : unable to find resource 'VM_global_library.vm' in
>> any resource loader.*
>> *Velocimacro : error using VM library template VM_global_library.vm
>> : org.apache.velocity.exception.ResourceNotFoundException: Unable to
>> find resource 'VM_global_library.vm'*
>> Velocimacro : VM library template macro registration complete.
>> Velocimacro : allowInline = true : VMs can be defined inline in templates
>> Velocimacro : allowInlineToOverride = false : VMs defined inline may
>> NOT replace previous VM definitions
>> Velocimacro : allowInlineLocal = false : VMs defined inline will be
>> global in scope if allowed.
>> Velocimacro : initialization complete.
>> Velocity successfully started.
>> Loading source files for package mypkg...
>> Loading source files for package mypkg.html...
>> Constructing Javadoc information...
>> Javadoc Warnings
>> Feb 13, 2013 9:16:15 AM
>> com.sun.jersey.wadl.resourcedoc.ResourceDoclet start
>> INFO: Wrote /home/najmi/myproject/target/classes/resourcedoc.xml
>>
>> *My pom configures the maven-javadoc-plugin much the same way as the
>> "Generate WADL - Jersey Sample". One difference is that since I do
>> not have a custom ExampleDocProcessor I do not specify -processors
>> output. I think this is where my problem lies. **
>>
>> *Here is that part of the pom.xml file:
>>
>> <!-- <additionalparam>-output
>> ${project.build.outputDirectory}/resourcedoc.xml -processors
>> com.sun.jersey.samples.generatewadl.util.ExampleDocProcessor</additionalparam>-->
>> <additionalparam>-output
>> ${project.build.outputDirectory}/resourcedoc.xml</additionalparam>
>>
>>
>> Could someone please try and offer some help. Thanks.
>>
>> On 02/12/2013 01:02 PM, Farrukh Najmi wrote:
>>> Hi Guys,
>>>
>>> Any one able to offer some advice on this? Thanks.
>>>
>>> On 02/08/2013 07:13 PM, Farrukh Najmi wrote:
>>>> Hi Guys,
>>>>
>>>> The next issue in my attempt at generating application.wadl using
>>>> the generate-wadl sample as an example is that I am not seeing any
>>>> <doc> elements corresponding to the @param javadoc tags for
>>>> QueryParams in my resource's GET method.
>>>>
>>>> Please note that I am not using any custom DocProcessor or
>>>> WadlGenerator and have nothing similar to the
>>>> com.sun.jersey.samples.generatewadl.util package classes in my app.
>>>> Are they significant to the missing <doc> element for the @param
>>>> javadoc tags?
>>>>
>>>> How are they generated and what would cause them to be missing?
>>>>
>>>> Thanks for your help.
>>>>
>>>
>
--
Regards,
Farrukh Najmi
Web: http://www.wellfleetsoftware.com