Pull Pojo DTO documentation, report layout and link handling #26
Conversation
…in jax.DocletWriter
…et pages so we have top and bottom CSS classes applied to all menus. Styling of the bottom menu can now be distinct from the top menu (e.g. to add more margin-top on the index pages).
…n POJO style DTO serialization is being used: -enablepojojson : a flag that activates DTO documenation -matchingpojonamesonly : a regex for types to generate DTO documentation for
…etWriter as a superclass, removing redundant printOtherMenuItems methods.
…S resource methods when DTO serialization is done using a Pojo style (i.e. Jackson POJO -> JSON serialization). Data object types that are not external, but are resolvable in the current Javadoc source path (which can be extended using standard javadoc include mechanisms) are documented at a field level, and linked from the method details. A new top level Data objects page is generated and added to the menu, listing all data objects resolved during resource documentation.
…space at bottom of pre block in documenation.
…ame that show the fully qualified type name.
- Make the resource method sections distinct and with a consistent structure - Make the resource list and method list tables distinct and with a similar structure to the method details section - Remove the examples table if only one example is shown, to simplify styling
…tion only (without a DocletWriter), for use where the DocletWriter context may not be available.
…ted Javadoc with links etc.
…d resource classes.
{@link ResourceClass/ResourceLocatorClass} is now supported, as is {@link ResourceClass#resourceMethod()}.
Resource method links are labelled with the HTTP method(s) of the resource, while resource class links link directly to the resource path.
ResourceClass/Locator type hierarchies are followed, so resource locator extension/interface implementation is allowed.
…be documented based on a regular expression. This is useful when you are including DTOs from a shared source path that also includes resources (i.e. you're developing two distinct web services that share DTOs).
|
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: |
…a JAXBType) prior to documenting an input/output.
…arameters, not the enclosing type, to allow interface methods to be matched to implementation class methods.
- utilising the full local type name for the file, not just the simple type name) - using the simple type name for the display text
…TO is an inner class.
… (class extension only) DTOs. Superclass is now reported in index and data object page. Subclasses are listed in data object page.
…hey have generic type information.
|
@timw: I really want to merge your stuff, did you take a look at my previous questions? Also I have a question regarding |
|
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. The @link support is all in JAXRSHtmlDocletWriter.seeTagToString(SeeTag). cheers ----- Original Message ----- From: "Stéphane Épardaud" reply@reply.github.com @timw: I really want to merge your stuff, did you take a look at my previous questions? Also I have a question regarding Reply to this email directly or view it on GitHub: |
|
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 I guess I'll need to add support for it in the other doclets too. |
|
For info, |
|
Tidying was just getting the docs + test cases up to date so you could see what was going on. 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. cheers ----- Original Message ----- From: "Stéphane Épardaud" reply@reply.github.com 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 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: |
|
Be very happy to see this in a release; I'm likely not jiggy enough with git to test it before then. |
…ntation to complement the jaxrs and jaxrs-minimal.
…ake documented paths for root resource methods consistent with other resource methods.
…in the Pojo type generation: * Objects * Documentation of properties based on JavaBean style methods * Polymorphic DTOs * Enumerated types * Handling of parameterized types (where the type parameters should be documented, but not the generic type)
… discover documentable DTOs in generic collections.
… property accessors (rather than fields). This is more likely to be what JSON serializers (such as Jackson) use (although there is a lot of flexibility in these tools around method and visibility rules). Future work might require looking at fields, a bunch of serializer specific annotations, and using configuration options to the docket (for the config based serialization policies that can't be derived from code).
These are displayed distinctly in the data object list, and have a different style in the data object detail (modeled after the Javadoc presentation of enums).
… accessors. This could probably be better done by adding per-serializer modes, but this is the most common case.
- -matchresourcesonly configuration option
- Support for Class factory based resource locator methods
- Linking (via {@link fu} inline doclets) in JAX-RS documentation
- POJO JSON documentation
Conflicts: doclets/src/main/java/com/lunatech/doclets/jax/jaxrs/JAXRSDoclet.java doclets/src/main/java/com/lunatech/doclets/jax/jaxrs/model/Resource.java doclets/src/main/java/com/lunatech/doclets/jax/jaxrs/model/ResourceMethod.java doclets/src/main/java/com/lunatech/doclets/jax/jaxrs/writers/MethodWriter.java doclets/src/main/java/com/lunatech/doclets/jax/writers/DocletWriter.java
|
OK, I've finally found some time to work on this.
|
|
On the subject of
These two were the additions I made. It also (due to built-in JavaDoc functionality) works with:
|
Included tests for invalid DTO, resource class and resource method @links. Also made the link generation more resilient and focused - it only tries to look for resource methods if it found a resource class now.
Test examples also included.
|
OK, this is fantastic work, thanks a lot! |
Pull Pojo DTO documentation, report layout and link handling
|
@timw if you want to become committer on jax-doclets, let me know. |
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.