search

FroMage / jax-doclets

Set of JavaDoc doclets for modern Java annotations APIs
http://www.lunatech-labs.com/open-source/jax-doclets
GNU Lesser General Public License v3.0
26 stars 23 forks source link

Pull Pojo DTO documentation, report layout and link handling #26

Closed timw closed 12 years ago

timw commented 12 years ago

We've been making some local improvements to the JAX-RS doclet to handle our setup (POJO style Jackson serialization) and improve the produced reports.

Notably:

I've done one pull request so you can have a look at the improvements to date, but let me know if you want it chunked up a bit finer.

FroMage commented 12 years ago

Hey this looks great, I want to merge that in, as soon as I take a look at the resulting HTML (the code looks good).

But unfortunately when I run the tests I get this exception:

$ mvn -pl doclets integration-test
[...]

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.NullPointerException
    at com.lunatech.doclets.jax.jaxrs.writers.MethodWriter.printOutputGenericType(MethodWriter.java:219)
    at com.lunatech.doclets.jax.jaxrs.writers.MethodWriter.printOutputType(MethodWriter.java:213)
    at com.lunatech.doclets.jax.jaxrs.writers.MethodWriter.printOutput(MethodWriter.java:181)
    at com.lunatech.doclets.jax.jaxrs.writers.MethodWriter.printMethod(MethodWriter.java:95)
    at com.lunatech.doclets.jax.jaxrs.writers.MethodWriter.print(MethodWriter.java:60)
    at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.printMethodDetails(ResourceWriter.java:119)
    at com.lunatech.doclets.jax.jaxrs.writers.ResourceWriter.write(ResourceWriter.java:63)
    at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:160)
    at com.lunatech.doclets.jax.jaxrs.model.Resource.write(Resource.java:163)
    at com.lunatech.doclets.jax.jaxrs.JAXRSDoclet.start(JAXRSDoclet.java:111)
    at com.lunatech.doclets.jax.jaxrs.JAXRSDoclet.start(JAXRSDoclet.java:86)
    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)
timw commented 12 years ago

But unfortunately when I run the tests I get this exception:

I've figured out how to run the integration tests (would you believe it's the first time I've used Maven in a project) and sorted that out.

I've also tidied up the Pojo documentation (generated files and links) to be more consistent with the existing JAXB linking, and added handling for DTO field types in DTOs and subclassed DTOs.

Also added a couple of examples of resource method linking.

FroMage commented 12 years ago

Yeah, sorry about Maven, moving this project to Maven was my million dollar mistake ;)

That looks all fine, but even when I modify my tests to add the -enablepojojson flag, my "data objects" tab only contains an empty Response object. So I still can't really see what this is all about. Do you mind adding some tests to illustrate what this tab does?

Also, did you add documentation to the manual about the new @link tag and the new pojo parameters?

Thanks a lot.

FroMage commented 12 years ago

@timw: I really want to merge your stuff, did you take a look at my previous questions?

Also I have a question regarding @link support: I don't see where you did anything to support it, I only see a method related to SeeTag, but that's not the same, right? I'm asking because another user is having issues with @link at #37.

timw commented 12 years ago

Hi

I'm trying to get some time to work on this in the next week. I'll see if I can tidy up as requested and update the pull request. I've also got a bunch of local fixes pending that I'll do at the same time.

The @link support is all in JAXRSHtmlDocletWriter.seeTagToString(SeeTag).

cheers tim

----- Original Message -----

From: "Stéphane Épardaud" reply@reply.github.com To: "Tim Whittington" Tim.Whittington@orionhealth.com Sent: Wednesday, 14 March, 2012 11:03:49 PM Subject: Re: [jax-doclets] Pull Pojo DTO documentation, report layout and link handling (#26)

@timw: I really want to merge your stuff, did you take a look at my previous questions?

Also I have a question regarding @link support: I don't see where you did anything to support it, I only see a method related to SeeTag, but that's not the same, right? I'm asking because another user is having issues with @link at #37.

Reply to this email directly or view it on GitHub: https://github.com/FroMage/jax-doclets/pull/26#issuecomment-4495256

FroMage commented 12 years ago

OK thanks a lot. I don't need tidying (but feel free to if you want), I need to see an example of what this does :) And documentation.

So @link is supported by SeeTag, OK that makes sense. That will need documenting too. Does it work for any reference to a java type, including JDK types like regular javadoc's @link?

I guess I'll need to add support for it in the other doclets too.

FroMage commented 12 years ago

For info, @link support was first requested in #1

timw commented 12 years ago

Tidying was just getting the docs + test cases up to date so you could see what was going on. I also wanted to fix the DTO documentation so it works on JavaBean style getters (currently naively does fields).

The implementation just delegates to the standard implementation for links that don't resolve to resource methods, so it should work for standard Java behaviour. (One side effect of this is that if you create an invalid link, it'll still put it in as if you were pointing to a Java object).

cheers tim

----- Original Message -----

From: "Stéphane Épardaud" reply@reply.github.com To: "Tim Whittington" Tim.Whittington@orionhealth.com Sent: Wednesday, 14 March, 2012 11:26:35 PM Subject: Re: [jax-doclets] Pull Pojo DTO documentation, report layout and link handling (#26)

OK thanks a lot. I don't need tidying (but feel free to if you want), I need to see an example of what this does :) And documentation.

So @link is supported by SeeTag, OK that makes sense. That will need documenting too. Does it work for any reference to a java type, including JDK types like regular javadoc's @link?

I guess I'll need to add support for it in the other doclets too.

Reply to this email directly or view it on GitHub: https://github.com/FroMage/jax-doclets/pull/26#issuecomment-4495587

MaggieLeber commented 12 years ago

Be very happy to see this in a release; I'm likely not jiggy enough with git to test it before then.

timw commented 12 years ago

OK, I've finally found some time to work on this.

timw commented 12 years ago

On the subject of @link, it works for:

These two were the additions I made.

It also (due to built-in JavaDoc functionality) works with:

FroMage commented 12 years ago

OK, this is fantastic work, thanks a lot!

FroMage commented 12 years ago

@timw if you want to become committer on jax-doclets, let me know.