fromage / jax-doclets Goto Github PK

Hi.

I'm coming from stoicflame/enunciate#530 and I'm wondering if such a thing could be added to jax-doclets.

Thanks!

I'm trying to generate RESTful docs for external consumption. The "API Example:" section showing the Java example on how to call the method is meaningless (and confusing) for parties which will only consume the REST API.

Is there a way to disable this section upon documentation generation?

Note: You can "hide" this via a CSS selector, but that's more of a hack since there's no current cross-browser CSS selector that will allow you to hide the nth td element (thanks IE).

Reported by [email protected], Jul 19, 2011
What steps will reproduce the problem?
1.Add some comment to the class level such as:

/**

• description
  */
  @path("/mypath")
  @produces(MediaType.APPLICATION_JSON)
  public class MyClass { ... }

What is the expected output? What do you see instead?
In the resources table containing /mypath there is no information in the description column

What version of the product are you using? On what operating system?
v0.9.0 - WinXP/Linux

Please provide any additional information below.
Please indicate the proper way to add comments at that level.

Reported by [email protected], Jul 4, 2011
What steps will reproduce the problem?

1. build subresource (e.g. /test/{id}/example)
2. run jax rs doclet
3. deploy to webserver and inspect overview-summary.html

What is the expected output? What do you see instead?
expected: <a href="test/{id}/example/index.html">...
result is: <a href="test\{id}\example/index.html">...

What version of the product are you using? On what operating system?
v0.9.0
Windows 7

Please provide any additional information below.
The path to the resource is build with the system file separator in Utils.java. On windows systems "File.separator" returns "". This can't be used as url path...

Usually, path parameters are self-explanatory. However it is useful under certain circumstances or for verbosity to have each path parameter documented.

Currently the matching @param only shows up in the "API Example:" section. It would be great if a "Path Parameters:" section was added alongside the "Input:"/"Output:"/"Query parameters:"/etc. sections.

Note, the string name of the parameter inside @PathParam (ie: @PathParam("foo")) should just be for display purposes so java variables can be named whatever is appropriate.

There are few places which output raw & (ampersand) character in the HTML source, like:

foo?bar&current_baz=...

which leads to undesired rendering (the least) like:

foo?bar¤t_baz=...

Proposed patch:

diff --git a/doclets/src/main/java/com/lunatech/doclets/jax/jaxrs/writers/IndexWriter.java b/doclets/src/main/java/com/lunatech/doclets/jax/jaxrs/writers/IndexWriter.java
--- a/doclets/src/main/java/com/lunatech/doclets/jax/jaxrs/writers/IndexWriter.java
+++ b/doclets/src/main/java/com/lunatech/doclets/jax/jaxrs/writers/IndexWriter.java
@@ -96,11 +96,11 @@
     around("tt", httpMethod);
     close("a");
     close("td");
     open("td");
     open("a href='" + path + "/index.html'");
-    around("tt", Utils.getDisplayURL(this, resource, method));
+    around("tt", escape(Utils.getDisplayURL(this, resource, method)));
     close("a");
     close("td");
     open("td");
     Doc javaDoc = method.getJavaDoc();
     if (javaDoc != null && javaDoc.firstSentenceTags() != null)
diff --git a/doclets/src/main/java/com/lunatech/doclets/jax/jaxrs/writers/MethodWriter.java b/doclets/src/main/java/com/lunatech/doclets/jax/jaxrs/writers/MethodWriter.java
--- a/doclets/src/main/java/com/lunatech/doclets/jax/jaxrs/writers/MethodWriter.java
+++ b/doclets/src/main/java/com/lunatech/doclets/jax/jaxrs/writers/MethodWriter.java
@@ -384,11 +384,11 @@
     if (!queryParameters.isEmpty()) {
       print("?");
       boolean first = true;
       for (String name : queryParameters.keySet()) {
         if (!first)
-          print("&");
+          print("&");
         print(name);
         print("=…");
         first = false;
       }
     }
@@ -414,11 +414,11 @@
     if (!formParameters.isEmpty()) {
       print("\n");
       boolean first = true;
       for (String name : formParameters.keySet()) {
         if (!first)
-          print("&");
+          print("&");
         print(name);
         print("=…");
         first = false;
       }
     }
diff --git a/doclets/src/main/java/com/lunatech/doclets/jax/jaxrs/writers/ResourceWriter.java b/doclets/src/main/java/com/lunatech/doclets/jax/jaxrs/writers/ResourceWriter.java
--- a/doclets/src/main/java/com/lunatech/doclets/jax/jaxrs/writers/ResourceWriter.java
+++ b/doclets/src/main/java/com/lunatech/doclets/jax/jaxrs/writers/ResourceWriter.java
@@ -84,11 +84,11 @@
         continue;
       for (String httpMethod : method.getMethods()) {
         open("tr");
         open("td");
         open("tt");
-        around("a href='#" + httpMethod + "'", httpMethod + " " + Utils.getDisplayURL(this, resource, method));
+        around("a href='#" + httpMethod + "'", httpMethod + " " + escape(Utils.getDisplayURL(this, resource, method)));
         close("tt");
         close("td");
         open("td");
         Doc javaDoc = method.getJavaDoc();
         if (javaDoc != null && javaDoc.firstSentenceTags() != null)

Reported by MatrixFrog, Aug 2, 2011
What steps will reproduce the problem?

1. Create a JAX-RS method that takes multiple query parameters, one of which is "regex", like:

@path("resource")
@get
public void getResource(@QueryParam("status") String status, @QueryParam("regex") String regex) {...}

1. Generate JAX-RS documentation for the method.

What is the expected output? What do you see instead?
You expect the output to include something like "GET /resource?status=�&regex=�" but instead you see "GET /resource?status=�®ex=�"

What version of the product are you using? On what operating system?
0.9.0, Windows 7

Please provide any additional information below.
When you "view source" on the page, you see "GET /resource?status=�&regex=�" as expected. The browser (I'm using the Aurora build of Firefox, but I assume most other browsers will do the same thing -- I can try them out if you want) sees "&reg" and it assumes the author meant to write "®" which is the HTML entity for ®, so it displays ®. I would argue the browser is technically wrong, but if the HTML contained "GET /resource?status=�&regex=�" then there would be no ambiguity.

Alternatively, maybe using a particular HTML doctype declaration or something like that, will tell the browser not to be "clever" and only interpret entities that are written properly?

Reported by [email protected], Jun 7, 2011
A nice feature will be possibility to put custom text in 'HTTP Example' section so I can provide my own example HTTP request and example HTTP response (even more than once). Some new annotations will be required i.e. @exampleRequest and @exampleResponse.

What do you think?

Duplicate with Issue 26 from code.google.com tracker.

When I use resource with a Path with regexp like .+,.+, doclet cannot create directory.
It seems doclet removes several regexp expressions from path, but not all of them.

What steps will reproduce the problem?
1.Create a resource with a Path annotation with a regex. Example:
@path("contact/{contactIds : .+,.+}")
2. Run the jax doclet against the project.
3. You will get a stack trace about not being able to create the directory from the doclet. See below.

What version of the product are you using?
0.8.0
0.9.0
0.10.0

On what operating system?
Windows 7

Call stack:
Embedded error: Error rendering Maven report:
Exit code: 1 - javadoc: error - Unable to create directory D:/target/site/jaxrsdocs\v1.0\account{accountId}\address-book\contact{contactIds : .+,.+}
javadoc: error - In doclet class com.lunatech.doclets.jax.jaxrs.JAXRSDoclet, method start has thrown an exception java.lang.reflect.InvocationTargetException
com.sun.tools.doclets.internal.toolkit.util.DocletAbortException
at com.sun.tools.doclets.internal.toolkit.util.DirectoryManager.createDirectory(DirectoryManager.java:263)
at com.sun.tools.doclets.internal.toolkit.util.Util.genWriter(Util.java:576)
at com.sun.tools.doclets.formats.html.markup.HtmlWriter.(HtmlWriter.java:61)
at com.sun.tools.doclets.formats.html.markup.HtmlDocWriter.(HtmlDocWriter.java:47)
at com.sun.tools.doclets.formats.html.HtmlDocletWriter.(HtmlDocletWriter.java:95)
at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.getWriter(ResourceWriter.java:43)
at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.(ResourceWriter.java:37)
at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:165)
at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:169)
at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:169)
at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:169)
at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:169)
at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:169)
at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:169)
at com.lunatech.doclets.jax.jaxrs.JAXRSDoclet.start(JAXRSDoclet.java:106)
at com.lunatech.doclets.jax.jaxrs.JAXRSDoclet.start(JAXRSDoclet.java:78)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
at java.lang.reflect.Method.invoke(Method.java:597)
at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:269)
at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:143)
at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:340)
at com.sun.tools.javadoc.Start.begin(Start.java:128)
at com.sun.tools.javadoc.Main.execute(Main.java:41)
at com.sun.tools.javadoc.Main.main(Main.java:31)

One way to avoid having to implement a ton of one-off annotations or parameters could be to add the ability to specify a post-process XSLT document. This way if someone wants to add/remove/modify certain elements of the resulting docs, they can do so.

This would essentially be the catch-all but care should be taken to to rely on it too heavily instead of providing first-class support for common use cases.

(although there may already be a maven plugin somewhere that could pickup this step... need to research)

Reported by [email protected], Jun 1, 2011
Hi!

First of all, thank you for this great tool. It's saved me a lot of time because now I can keep documentation of rest endpoints close to code and don't worry that documentation will be about up-to-date.

I don't know if it bug or design chose but currently it's only possible to generate documentation of server side (sooner or later some class has to use or implement an interface with JAX-RS annotations).
I would like to use jax-doclets also to document client side. With resteasy it's possible to use JAX-RS annotated interfaces to create rest client. Those interfaces aren't implemented by any classes so they are omitted by jax-doclet. This feature will be especially useful if rest endpoints (server side) aren't implemented in java and it's easier to create sample client (using java and jax-rs) and put documentation here.

It seems that with Java 8 every is broken.

I started to do some changes but it feels like this is going to be a lot of rework, the doclet API has been through massive changes..

Unfortunately I cannot find a lot of details about this API online. I'd like to contribute but I wondering what the best solution would be.

I find that "Root resource" is more confusing to readers than anything else and is a bit frustrating that it is mapped to index.html.

What would be nice is if there was a way to specify which top-level menu items appear or at least which ones map to what html page so it could default to a different view in index.html.

At the very least, I think it would be better if "Overview" (overview-summary.html) was actually index.html since IMO its contents is the most useful/readable.

I am getting a file not found exception (permission denied) for /doclet.css using the 0.9 jar download and trying to run the jaxb doclets from ant:

I get the following stack.
[javadoc] javadoc: error - In doclet class com.lunatech.doclets.jax.jaxb.JAXBDoclet, method start has thrown an exception java.lang.reflect.InvocationTargetException
[javadoc] java.lang.RuntimeException: java.io.FileNotFoundException: /doclet.css (Permission denied)
[javadoc] at com.lunatech.doclets.jax.Utils.copyResource(Utils.java:453)
[javadoc] at com.lunatech.doclets.jax.Utils.copyResources(Utils.java:438)
[javadoc] at com.lunatech.doclets.jax.jaxb.JAXBDoclet.start(JAXBDoclet.java:110)
[javadoc] at com.lunatech.doclets.jax.jaxb.JAXBDoclet.start(JAXBDoclet.java:93)
[javadoc] at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
[javadoc] at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:48)
[javadoc] at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
[javadoc] at java.lang.reflect.Method.invoke(Method.java:600)
[javadoc] at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:269)
[javadoc] at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:143)
[javadoc] at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:340)
[javadoc] at com.sun.tools.javadoc.Start.begin(Start.java:128)
[javadoc] at com.sun.tools.javadoc.Main.execute(Main.java:41)
[javadoc] at com.sun.tools.javadoc.Main.main(Main.java:31)
[javadoc] Caused by: java.io.FileNotFoundException: /doclet.css (Permission denied)
[javadoc] at java.io.FileOutputStream.open(Native Method)
[javadoc] at java.io.FileOutputStream.(FileOutputStream.java:194)
[javadoc] at java.io.FileOutputStream.(FileOutputStream.java:145)
[javadoc] at com.lunatech.doclets.jax.Utils.copyResource(Utils.java:443)

The jar file does contain the file, so I don't quite know why it can't open it. The jar is +rw for my userid.

I have just started playing with jax-doclets, and the output examples for the jaxb output are coming out with values which would be xml attributes with a leading @ in the name.
e.g. XML
<application
isRunEnabled="xsd:boolean" ....

JSON:
{'application':
{
'@isRunEnabled': Boolean, ....

My runtime engine (wink+jackson+jaxb on tomcat) does not render the json fields in this way (which is annoying but so be it). Is there any option or flag I can set to not describe the json fields in this way? My only other alternative is to hide the json examples, but I would quite like to show them.

I want to add the following JAX-RS documentation to a REST @get method, so that I can link to
another resource method's documentation:

/**
 * The list of comments on the item, in reverse chronological order.
 * 
 * @param key The item creator’s organisation key, followed by an asterisk, followed by the 

item number.
* @http 400 Client errors are the same as for {@link #getItem(String, Request)}.
*/

However, in the HTML output this is rendered literally, instead of as a hyperlink.

jax-doclets-0.5

I use one parent pom with reporting for JAXB, JAX-RS and JPA. It works fine if child project contains all these parts. But if child project doesn't contains any persistence annotations it fails to build all docs (euther JAXB and JAX-RS).

I am trying to get maven to generate a jax-rs api doc with links to generated jaxb docs. I configured it according to the wiki, but for some reason, the jaxb docs are generated, the jax-rs task is not run. Does anyone has an working example or can point out what is wrong in the below pom-exerpt?

<reporting>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.7</version>
            <reportSets>
                <reportSet>
                    <id>jaxb</id>
                    <configuration>
                        <doclet>com.lunatech.doclets.jax.jaxb.JAXBDoclet</doclet>
                        <docletArtifacts>
                            <docletArtifact>
                                <groupId>com.lunatech.jax-doclets</groupId>
                                <artifactId>doclets</artifactId>
                                <version>0.10.0</version>
                            </docletArtifact>
                        </docletArtifacts>
                    </configuration>
                    <reports>
                        <report>javadoc</report>
                    </reports>
                </reportSet>
                <reportSet>
                    <id>jaxrs</id>
                    <configuration>
                        <doclet>com.lunatech.doclets.jax.jaxrs.JAXRSDoclet</doclet>
                        <docletArtifacts>
                            <docletArtifact>
                                <groupId>com.lunatech.jax-doclets</groupId>
                                <artifactId>doclets</artifactId>
                                <version>0.10.0</version>
                            </docletArtifact>
                        </docletArtifacts>
                             <additionalparam>-link ${project.build.directory}/site/spidocs</additionalparam>
                    </configuration>
                    <reports>
                        <report>javadoc</report>
                    </reports>
                </reportSet>
            </reportSets>
        </plugin>
    </plugins>
</reporting>

Per JSON specification the property names should be double quoted, otherwise it is invalid JSON syntax. The generated examples are not fully JSON "compatible" but they could be made a bit more useful by making the property name output compliant, anyway.

Proposed patch:

diff --git a/doclets/src/main/java/com/lunatech/doclets/jax/jaxb/writers/JAXBClassWriter.java b/doclets/src/main/java/com/lunatech/doclets/jax/jaxb/writers/JAXBClassWriter.java
--- a/doclets/src/main/java/com/lunatech/doclets/jax/jaxb/writers/JAXBClassWriter.java
+++ b/doclets/src/main/java/com/lunatech/doclets/jax/jaxb/writers/JAXBClassWriter.java
@@ -249,25 +249,25 @@

   private void printJSONExample() {
     around("b", "JSON Example:");
     open("pre");
     if(((JAXBConfiguration)configuration).enableJSONTypeName)
-      print("{'" + jaxbClass.getName() + "':\n");
+      print("{\"" + jaxbClass.getName() + "\":\n");
     print(" {\n");
     Collection<Attribute> attributes = jaxbClass.getAttributes();
     for (Attribute attribute : attributes) {
-      print("  '@");
+      print("  \"@");
       around("a href='#m_" + attribute.getName() + "'", attribute.getName());
-      print("': ");
+      print("\": ");
       printJSONMemberType(attribute, false);
       print(",\n");
     }
     Collection<Element> elements = jaxbClass.getElements();
     for (Element element : elements) {
-      print("   '");
+      print("   \"");
       around("a href='#m_" + element.getName() + "'", element.isWrapped() ? element.getWrapperName() : element.getName());
-      print("': ");
+      print("\": ");
       printJSONMemberType(element, true);
       print(",\n");
     }
     for (Value value : jaxbClass.getValues()) {
       print("   ");

If I have a resource named 'options':

@path("/options")
@produces(MediaType.APPLICATION_JSON)
public class OptionResource

I get the following failure when running mvn site:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-site-plugin:3.2:site (default-site) on project Blah-webapp: Error during page generation: Error rendering Maven report:
[ERROR] Exit code: 1 - javadoc: error - In doclet class com.lunatech.doclets.jax.jaxrs.JAXRSDoclet, method start has thrown an exception java.lang.reflect.InvocationTargetException
[ERROR] java.lang.RuntimeException: java.io.FileNotFoundException: /home/blah/workspace/Blah/Blah-webapp/target/site/apidocs/options/index.html (Not a directory)
[ERROR] at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.getWriter(ResourceWriter.java:45)
[ERROR] at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.(ResourceWriter.java:37)
[ERROR] at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:165)
[ERROR] at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:169)
[ERROR] at com.lunatech.doclets.jax.jaxrs.JAXRSDoclet.start(JAXRSDoclet.java:106)
[ERROR] at com.lunatech.doclets.jax.jaxrs.JAXRSDoclet.start(JAXRSDoclet.java:78)
[ERROR] at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
[ERROR] at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
[ERROR] at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
[ERROR] at java.lang.reflect.Method.invoke(Method.java:601)
[ERROR] at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:280)
[ERROR] at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:160)
[ERROR] at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:397)
[ERROR] at com.sun.tools.javadoc.Start.begin(Start.java:167)
[ERROR] at com.sun.tools.javadoc.Main.execute(Main.java:59)
[ERROR] at com.sun.tools.javadoc.Main.main(Main.java:49)
[ERROR] Caused by: java.io.FileNotFoundException: /home/blah/workspace/Blah/Blah-webapp/target/site/apidocs/options/index.html (Not a directory)
[ERROR] at java.io.FileOutputStream.open(Native Method)
[ERROR] at java.io.FileOutputStream.(FileOutputStream.java:212)
[ERROR] at java.io.FileOutputStream.(FileOutputStream.java:104)
[ERROR] at com.sun.tools.doclets.internal.toolkit.util.Util.genWriter(Util.java:646)
[ERROR] at com.sun.tools.doclets.formats.html.markup.HtmlWriter.(HtmlWriter.java:169)
[ERROR] at com.sun.tools.doclets.formats.html.markup.HtmlDocWriter.(HtmlDocWriter.java:65)
[ERROR] at com.sun.tools.doclets.formats.html.HtmlDocletWriter.(HtmlDocletWriter.java:118)
[ERROR] at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.getWriter(ResourceWriter.java:43)
[ERROR] ... 15 more

If I change the URI of the resource it works. The maven-javadoc-plugin is generating an options file that it uses when calling javadoc (javadoc @options) and this is conflicting with the options folder the jax-doclets tries to create.

Maven's javadoc plugin only allows filtering by Java package which doesn't map nicely to URI path structures. Having the ability to include/exclude the documentation that will be generated based on JAXRS paths (allowing for wild-carding syntax) would be nice.

I ended up with an NoSuchMethodError on Oracle JDK 8. Is there a workaround or fix available?

Doclet Version: 0.10.1
Javadoc Plugin: 2.10.1
Maven: 3.2.2
Oracle JDK: jdk1.8.0_25

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-site-plugin:3.3:site (default-site) on project xxxxxxxxxxxx: Error during page generation: Error rendering Maven report:
[ERROR] Exit code: 1 - javadoc: error - In doclet class com.lunatech.doclets.jax.jaxrs.JAXRSDoclet,  method start has thrown an exception java.lang.reflect.InvocationTargetException
[ERROR] java.lang.NoSuchMethodError: com.sun.tools.doclets.formats.html.HtmlDocletWriter.<init>(Lcom/sun/tools/doclets/formats/html/ConfigurationImpl;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V
[ERROR] at com.lunatech.doclets.jax.jaxrs.writers.JAXRSHtmlDocletWriter.<init>(JAXRSHtmlDocletWriter.java:25)
[ERROR] at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.getWriter(ResourceWriter.java:45)
[ERROR] at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.<init>(ResourceWriter.java:39)
[ERROR] at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:162)
[ERROR] at com.lunatech.doclets.jax.jaxrs.JAXRSDoclet.start(JAXRSDoclet.java:118)
[ERROR] at com.lunatech.doclets.jax.jaxrs.JAXRSDoclet.start(JAXRSDoclet.java:90)
[ERROR] at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
[ERROR] at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
[ERROR] at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
[ERROR] at java.lang.reflect.Method.invoke(Method.java:483)
[ERROR] at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:310)
[ERROR] at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:189)
[ERROR] at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:366)
[ERROR] at com.sun.tools.javadoc.Start.begin(Start.java:219)
[ERROR] at com.sun.tools.javadoc.Start.begin(Start.java:205)
[ERROR] at com.sun.tools.javadoc.Main.execute(Main.java:64)
[ERROR] at com.sun.tools.javadoc.Main.main(Main.java:54)
[ERROR] 
[ERROR] Command line was: "C:\Program Files\Java\jdk1.8.0_25\jre\..\bin\javadoc.exe" @options @packages

Please add support for -link also for multiple JAXB projects - when one JAXB annotated class refers other from different project. Currently the referenced classes are in-lined.

I'm a bit baffled why there is no support for JAX-WS at all. SOAP may not be the most popular protocol but still it is widely used. If you are not opposed to the idea, I may work on it, provided I find some time (which unfortunately is unlikely in the near future 😕).

My current project is using EclipseLink moxy. Some code is using @XmlPath of EclipseLink moxy to define a fine mapping between Java object and xml schema.
And I also using jax-doclets to generate docs. Now my RestFul API is working as I expected with fine mapping. But the API doc which is generated by jax-doclets didn't follow my fine mapping setting on @XmlPath .

So my question is :

does jax-doclets support EclipseLink moxy?

some of my code like this :

@XmlPath("phones/phone[@type='home']/text()")
public String getHomePhone() {
    return homePhone;
}

@XmlPath("phones/phone[@type='work']/text()")
public String getWorkPhone() {
    return workPhone;
}

.....

The build of the current development version 0.9.1-SNAPSHOT fails under Windows:

...>mvn install
...
[INFO] [javadoc:test-javadoc {execution: jaxrs}]
[INFO] 
Loading source files for package com.lunatech.doclets.jax.jaxb...
Loading source files for package com.lunatech.doclets.jax.jaxb.testcase...
Loading source files for package com.lunatech.doclets.jax.test...
Loading source files for package com.lunatech.doclets.jax.test.demo.doc...
Loading source files for package com.lunatech.doclets.jax.test.demo.nodoc...
Loading source files for package com.lunatech.doclets.jax.test.demo...
Loading source files for package com.lunatech.doclets.jax.test.interfaces...
Loading source files for package com.lunatech.doclets.jax.test.jpa...
Constructing Javadoc information...
Generating .../jax-doclets/doclets/target/jaxrsdocs\index.html...
Generating .../jax-doclets/doclets/target/jaxrsdocs\doc-method-order\index.html...
1 error
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] An error has occurred in Test JavaDocs report generation: 
Exit code: 1 - javadoc: error - In doclet class com.lunatech.doclets.jax.jaxrs.JAXRSDoclet,  method start has thrown an exception java.lang.reflect.InvocationTargetException
java.lang.StringIndexOutOfBoundsException: String index out of range: 1
    at java.lang.String.charAt(String.java:686)
    at java.util.regex.Matcher.appendReplacement(Matcher.java:703)
    at java.util.regex.Matcher.replaceAll(Matcher.java:813)
    at java.lang.String.replaceAll(String.java:2189)
    at com.lunatech.doclets.jax.Utils.urlToSystemPath(Utils.java:348)
    at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.getWriter(ResourceWriter.java:42)
    at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.<init>(ResourceWriter.java:38)
    at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:161)
    at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:165)
    at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:165)
    at com.lunatech.doclets.jax.jaxrs.JAXRSDoclet.start(JAXRSDoclet.java:95)
    at com.lunatech.doclets.jax.jaxrs.JAXRSDoclet.start(JAXRSDoclet.java:67)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
    at java.lang.reflect.Method.invoke(Method.java:597)
    at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:269)
    at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:143)
    at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:340)
    at com.sun.tools.javadoc.Start.begin(Start.java:128)
    at com.sun.tools.javadoc.Main.execute(Main.java:41)
    at com.sun.tools.javadoc.Main.main(Main.java:31)

Command line was: C:\java\jdk1.6.0_x64\jre\..\bin\javadoc.exe @options @packages

Refer to the generated Javadoc files in '...\jax-doclets\doclets\target\jaxrsdocs' dir.

The problem appears the following line in com.lunatech.doclets.jax.Utils.urlToSystemPath():

    return name.replaceAll("/", File.separator);

This fails because under Windows the File.separator happens to match the regex escape character. So it should either get escaped properly:

diff --git a/doclets/src/main/java/com/lunatech/doclets/jax/Utils.java b/doclets/src/main/java/com/lunatech/doclets/jax/Utils.java
--- a/doclets/src/main/java/com/lunatech/doclets/jax/Utils.java
+++ b/doclets/src/main/java/com/lunatech/doclets/jax/Utils.java
@@ -343,11 +343,11 @@

   public static String urlToSystemPath(Resource resource) {
     String name = resource.getAbsolutePath();
     if (name.startsWith("/"))
       name = name.substring(1);
-    return name.replaceAll("/", File.separator);
+    return name.replaceAll("/", Matcher.quoteReplacement(File.separator));
   }

   public static String urlToClass(JAXBClass from, JAXBClass to) {
     return classToRoot(from) + classToPath(to) + "/" + to.getShortClassName() + ".html";
   }

Or use the simpler and probably faster String.replace(char, char):

diff --git a/doclets/src/main/java/com/lunatech/doclets/jax/Utils.java b/doclets/src/main/java/com/lunatech/doclets/jax/Utils.java
--- a/doclets/src/main/java/com/lunatech/doclets/jax/Utils.java
+++ b/doclets/src/main/java/com/lunatech/doclets/jax/Utils.java
@@ -343,11 +343,11 @@

   public static String urlToSystemPath(Resource resource) {
     String name = resource.getAbsolutePath();
     if (name.startsWith("/"))
       name = name.substring(1);
-    return name.replaceAll("/", File.separator);
+    return name.replace('/', File.separatorChar);
   }

   public static String urlToClass(JAXBClass from, JAXBClass to) {
     return classToRoot(from) + classToPath(to) + "/" + to.getShortClassName() + ".html";
   }

The structure of the HTML generated uses a lot of plain elements (table's, tr's, and td's especially). If these had "id" and/or "class" attributes, customizing with CSS would be easier.

javadoc: error - In doclet class com.lunatech.doclets.jax.jaxrs.JAXRSDoclet, method start has thrown an exception java.lang.reflect.InvocationTargetException
java.util.NoSuchElementException
at java.util.TreeMap$PrivateEntryIterator.nextEntry(TreeMap.java:1098)
at java.util.TreeMap$ValueIterator.next(TreeMap.java:1145)
at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.deepFilter(ResourceWriter.java:171)
at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.printSubresources(ResourceWriter.java:137)
at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.write(ResourceWriter.java:55)
at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:166)
at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:169)
at com.lunatech.doclets.jax.jaxrs.JAXRSDoclet.start(JAXRSDoclet.java:106)
at com.lunatech.doclets.jax.jaxrs.JAXRSDoclet.start(JAXRSDoclet.java:78)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
at java.lang.reflect.Method.invoke(Method.java:597)
at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:269)
at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:143)
at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:340)
at com.sun.tools.javadoc.Start.begin(Start.java:128)
at com.sun.tools.javadoc.Main.execute(Main.java:41)
at com.sun.tools.javadoc.Main.main(Main.java:31)

What is the expected output? What do you see instead?
I have specified everything as needed in classpath..it generates doc for few services and then throws this error. No explanation why.

A bean with a property of type java.util.Collection is not recognized as a collection.

If the comment contains multiple sentences only the first one is used. This is OK for summary, but there is no detailed documentation generated.

Example:

    /**
     * Query filter. See {@link User} for available fields.
     */
    @XmlElement
    private Filter filter;

Reported by [email protected], Jul 28, 2011
JAXB documentation doesn't consider the XMLElement's attributes like defaultValue, nillable,required

Currently in the elements section: Name, Type and description are displayed.
Add more columns for required,defaultValue and nillable attributes.

Does doclets provide any element to ignore some parameters from a resources method to not document them in the REST documentation ?

Reported by [email protected], Yesterday (22 hours ago)
What steps will reproduce the problem?

1. 2 maven modules, one with a jax-rs annotated inteface (module A) and one module with the implementation (module B).
2. Let a java class in module B implement the jax-rs annotated interface in module A.
3. generate the documentation for module B using maven. Note that the implementation class has no further java doc. Everything is on the interface.

What is the expected output? What do you see instead?
Expected is a documentation with all comments from the implemented interface but you get a documentation where all the rest resources are listed but without any java doc written on the interface. It seems that the java doc from the interface is completely ignored but the annotations from the interface are considered.

What version of the product are you using? On what operating system?
0.9.0 on WinXP/Linux.

Please provide any additional information below.

We need to make it more obvious how to use doclet params in maven and ant.

Reported by [email protected], Sep 9 (5 days ago)
What steps will reproduce the problem?

1. checkout latest trunk
2. run maven install

What is the expected output? What do you see instead?
I'd expect to get a doclets artifact for 0.9.1-SNAPSHOT, instead I'm getting build errors about missing dependencies.

What version of the product are you using? On what operating system?
Mac OS X, Maven 2.0.8, Java 1.6

Please provide any additional information below.
I've noticed that the jboss repository seems to be resolving incorrectly.

The parent pom.xml file has: https://repository.jboss.org/nexus, but when I build I see that it tries to download the resteasy jars from: https://repository.jboss.org/maven2

I checked out the project and tried a "mvn install", and it failed like this:

...
[INFO] [docbkx:generate-html {execution: generate-html}]
[INFO] Executing tasks
[INFO] Executed tasks
[INFO] Processing index.xml
Error on line 626 column 43 of file:///Users/blong/workspace/jax-doclets/docs/target/wikbook/src/index.xml:
Error reported by XML parser: Invalid byte 1 of 1-byte UTF-8 sequence.

A little research led me to docs/src/main/wikbook/en/en-US/running.wiki, which contains a curved single quote that apparently doesn't get translated right. Turning it into a normal single quote fixed the build for me (I'll add a pull request once I figure out how they work).

We are using jax-doclets to generate documentation from Java code and RESTeasy. Noticed that @Form annotated parameters appear as String in the generated documentation. For example:

@get
ResponseObjectClass someMethod(@Form RequestObjectClass request) { ... }

appears as:

Input:
String

Output:
ResponseObjectClass

in the generated documentation.

On page http://fromage.github.com/jax-doclets/docs/0.10.0/html/index.html is said:
"3.5 Supported RESTEasy JAX-RS extension annotations

If the optional RESTEasy dependency is present, the following RESTEasy annotations are supported on resource methods or classes:

@Form"

and we tried to add this optional RESTeasy dependency in the pom.xml, several times, at different places in the pom.xml - inside the for the JAXRSDoclet and outside of it, but none seems to work.

Can you please give an example how and where the optional RESTeasy dependency should be used in order to generate proper documentation for a @Form annotated parameter object.

Thank you.
Regards

I've been having trouble getting {@link} to work pointing to vanilla Javadoc of a POJO class rooted in a sibling directory to the JAX-RS docs when running from Maven.

My intent is to have ordinary Javadoc in target/site/apidocs and the JAX_RS in target/site/jaxrsdocs

But when I run

<reporting>
 <plugins>
  <plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>2.8</version>
  <reportSets>
  <reportSet>
  <id>javadoc</id>
  <reports><report>javadoc</report></reports>
  </reportSet>
 <reportSet>
 <id>jaxrs</id>
  <configuration>
  <doclet>com.lunatech.doclets.jax.jaxrs.JAXRSDoclet</doclet>
  <docletArtifacts>
   <docletArtifact>
    <groupId>com.lunatech.jax-doclets</groupId>
    <artifactId>doclets</artifactId>
    <version>0.10.0</version>
   </docletArtifact>
  </docletArtifacts>
  <description>Jax-RS RESTful services</description>
  <destDir>jaxrsdocs</destDir>
  <links><link>../apidocs</link></links>
 </configuration>
    <reports><report>javadoc</report></reports>
   </reportSet>
  </reportSets>
  </plugin>
  </plugins>
  </reporting>

and I code something like

 * @return the named {@link com.scala.cm.domain.content.Content}

it generates

<a href="../com/scala/cm/domain/content/Content.html" 
 title="class in com.scala.cm.domain.content">
<code>Content</code>
</a>

I'd expect the href to be to "../apidocs/com/scala/cm/domain/content/Content.html" instead because of

I hope this is a usage error on my part.

Support JAX-RS paths prefixing set in @ApplicationPath("/rest") annotation.

In code I have something like:

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("/rest")
public class RestApp extends Application {
}

import javax.ws.rs.GET;
import javax.ws.rs.Path;

public class RestResource {
  @GET @Path("/resource")
  public String getResource() {
    // ...
  }
}

So all JAX-RS paths are relative to /rest either if I use @Path("/resource") it will be mapped to /rest/resource. So in documentation path should be /rest/resource instead of /resource as it is now.

Maybe it works fine if servlet-mapping is set for javax.ws.rs.core.Application to /rest/*, I haven't tested.

Reported by [email protected], Aug 11, 2011
Currently.... In the elements table, the type is defined as xsd:any when the property is of type java.lang.Object. If there is an @XMLElements tag....Would it be a bad idea to display the list of @xmlelement info within the @XMLElements tag.

Example:
public class Foo{

@XMLElements(value={
@xmlelement(name="number",type=Integer.class),
@xmlelement(name="string",type=String.class)
})
private Object details;

}

Current Documentation: The type of the "details" element in Foo class is xsd:any.

Feature request: Can the type of the "details" element in Foo class
be ( {@link Integer.class} | {@link String.class} )

Jackson supports mapping Java Beans to/from JSON using JAXB annotations:

http://wiki.fasterxml.com/JacksonJAXBAnnotations

Its mapping is really simple and doesn't try to distinguish XML features like attributes (vs. elements) and namespaces, so both of the following two versions:

public class Foo {

    @XmlElement 
    public String bar;

    @XmlElement 
    public String baz;

}

and:

public class Foo {

    @XmlAttribute
    public String bar;

    @XmlElement 
    public String baz;

}

get serialized as:

{
    "bar" : "...",
    "baz" : "..."
}

and not as:

{
    "@bar" : "...",
    "baz" : "..."
}

It would be nice if there's an option to omit the @ in attribute names in the generated JSON examples, e.g. -useplainjsonattributenames, though this is a bit lengthy one.

Sorry to be a bore, but there are @OverRide annotations in the source code (e.g. ExcludeTaglet.java and some classes added/ changed over the last few days - PojoTypes.java, PojoClassWriter.java DataObjectIndexWriter.java) on methods that implement Interfaces rather than override superclasses.

The parent pom specifies a source and target of Java 1.5 - @OverRide on interface implementations isn't valid until 1.6.

The solution is either to change the pom to 1.6 or remove the @OverRide annotations. I'd vote for the second option unless there's a reason to move to 1.6 for the source?

Really minor point, but it causes compiler errors. :)

for service root, it does not take description.
It does not add that in index or on detail page.

/**

• Services for various testing related queries .
  */
  @path("/testingSvc")
  public class TestService {

I'm including the jaxrs-doclet generation in a multi-module Maven project. The servlet class is located in one of the child modules while the implementation and DAOs are in the other modules. I've tried various configurations based upon the provided user guide; however, no success. Upon executing the Maven site:site goal, the site directory is created with images and stylesheets used by Maven but nothing else.

Is there a way to generate output during the Maven build to debug the doclet? I'm not sure if it isn't find the appropriate class or if it isn't properly executing the doclet.

Source of the addition to my existing pom.xml:
http://www.lunatech-labs.com/files/jax-doclets/docs/0.9.0/html/index.html#d0e228

One of the powerful features of the RESTEasy @Form tag is that a @Form can have @Form fields within it, allowing reused field to be repeated across the services using common names and validation parameters.

However, it doesn't appear that jax-doclets recognises (or processes) fields that are annotated with an @Form tag.

In the API, any @Form paramters should be processed recursively, pulling-out all @...Param fields from all nested @Form objects and including them in the API document as if they were all just normal parameters (which is how RESTEasy handles them).

Great software btw :)

REST API calls that have several query string parameters cause the "Example HTML" section to horizontally stretch unbounded.

For a drop-in <pre> CSS class which can be used, see: http://stackoverflow.com/questions/248011/how-do-i-wrap-text-in-a-pre-tag

Perhaps limiting the scope of the style to <pre> elements only inside the example section (via CSS selectors) so it doesn't conflict with other <pre> tags might be wise. But then again, generic wrapping behavior described in stackoverflow link is pretty universally desirable.

For example:
`
/**

• Get the User object by primary key.
• @http 200 User was found.
• @http 404 User could not be found.
• @param uid
• @param request
• @return a wrapped {@link User} object
• @returnWrapped com.example.User
  */

`

generates:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-site-plugin:3.1:site (default-site) on project spring-mvc-jpa: Error during page generation: Error rendering Maven report:
[ERROR] Exit code: 1 - javadoc: error - In doclet class com.lunatech.doclets.jax.jaxrs.JAXRSDoclet, method start has thrown an exception java.lang.reflect.InvocationTargetException
[ERROR] java.lang.NullPointerException
[ERROR] at com.sun.tools.javadoc.ClassDocImpl.importedClasses(ClassDocImpl.java:1032)
[ERROR] at com.lunatech.doclets.jax.Utils.resolveType(Utils.java:648)
[ERROR] at com.lunatech.doclets.jax.Utils.setupType(Utils.java:789)
[ERROR] at com.lunatech.doclets.jax.Utils.parseType(Utils.java:737)
[ERROR] at com.lunatech.doclets.jax.jaxrs.writers.MethodWriter.printOutput(MethodWriter.java:163)
[ERROR] at com.lunatech.doclets.jax.jaxrs.writers.MethodWriter.printMethod(MethodWriter.java:83)
[ERROR] at com.lunatech.doclets.jax.jaxrs.writers.MethodWriter.print(MethodWriter.java:54)
[ERROR] at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.printMethodDetails(ResourceWriter.java:115)
[ERROR] at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.printMethods(ResourceWriter.java:68)
[ERROR] at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.write(ResourceWriter.java:56)
[ERROR] at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:166)
[ERROR] at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:169)
[ERROR] at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:169)
[ERROR] at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:169)
[ERROR] at com.lunatech.doclets.jax.jaxrs.JAXRSDoclet.start(JAXRSDoclet.java:106)
[ERROR] at com.lunatech.doclets.jax.jaxrs.JAXRSDoclet.start(JAXRSDoclet.java:78)
[ERROR] at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
[ERROR] at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
[ERROR] at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
[ERROR] at java.lang.reflect.Method.invoke(Method.java:597)
[ERROR] at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:269)
[ERROR] at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:143)
[ERROR] at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:340)
[ERROR] at com.sun.tools.javadoc.Start.begin(Start.java:128)
[ERROR] at com.sun.tools.javadoc.Main.execute(Main.java:41)
[ERROR] at com.sun.tools.javadoc.Main.main(Main.java:31)

Having parameters like "stylesheet", "header", "footer", "link" etc. are too generic and should be prefixed with some kind of unique identifier (ie: "com.lunatech.doclets") to avoid collision with other plugins.