Generate documentation based on interface (without any implementation) [PATCH]

[FroMage]

Reported by ragno...@gmail.com, 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.

[FroMage]

Eclipse Workspace Patch 1.0

#P doclets-jaxrs

Index: src/main/java/com/lunatech/doclets/jax/Utils.java

--- src/main/java/com/lunatech/doclets/jax/Utils.java (wersja 126)
+++ src/main/java/com/lunatech/doclets/jax/Utils.java (kopia robocza)
@@ -190,8 +190,6 @@
}

public static ClassDoc findAnnotatedClass(final ClassDoc klass, final Class<?>... soughtAnnotations) {

• if (!klass.isClass())

•  return null;
  

  if (hasAnnotation(klass, soughtAnnotations)) {
  return klass;
  }
  @@ -205,6 +203,8 @@
  if (superclass != null && superclass.asClassDoc() != null) {
  return findAnnotatedClass(superclass.asClassDoc(), soughtAnnotations);
  }
• return null;
  }

[FroMage]

Comment 1 by project member stephane.epardaud, Jun 1, 2011
Thanks for you patch, this is a good idea. However as it is your patch would modify the behaviour even for JAXB, and would cause documentation to be generated both for an implementing class (when there is one) and its interface.

I'll figure something out to make this work.

[FroMage]

Comment 2 by vdamme...@gmail.com, Aug 3, 2011
Hi,

we're storing jax-rs documentation on interfaces only and patched the Utils.java file as below. This generates only documentation for the interfaces, not for the implementing classes.

Tom

@@ -190,7 +190,7 @@
}

public static ClassDoc findAnnotatedClass(final ClassDoc klass, final Class<?>... soughtAnnotations) {

• if (!klass.isClass())
• if (klass.isClass())
  return null;
  if (hasAnnotation(klass, soughtAnnotations)) {
  return klass;