Javadoc comments for REST methods (#423)

Author: vojtechhabarta

typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/Javadoc.java

@@ -48,16 +48,21 @@ private static List<Root> loadJavadocXmlFiles(List<File> javadocXmlFiles) {
 
     public Model enrichModel(Model model) {
         final List<BeanModel> dBeans = new ArrayList<>();
-        final List<EnumModel> dEnums = new ArrayList<>();
         for (BeanModel bean : model.getBeans()) {
             final BeanModel dBean = enrichBean(bean);
             dBeans.add(dBean);
         }
+        final List<EnumModel> dEnums = new ArrayList<>();
         for (EnumModel enumModel : model.getEnums()) {
             final EnumModel dEnumModel = enrichEnum(enumModel);
             dEnums.add(dEnumModel);
         }
-        return new Model(dBeans, dEnums, model.getRestApplications());
+        final List<RestApplicationModel> dRestApplications = new ArrayList<>();
+        for (RestApplicationModel restApplication : model.getRestApplications()) {
+            final RestApplicationModel dRestApplication = enrichRestApplication(restApplication);
+            dRestApplications.add(dRestApplication);
+        }
+        return new Model(dBeans, dEnums, dRestApplications);
     }
 
     private BeanModel enrichBean(BeanModel bean) {
@@ -122,8 +127,36 @@ private EnumMemberModel enrichEnumMember(EnumMemberModel enumMember, Enum dEnum)
         return enumMember.withComments(Utils.concat(getComments(memberComment, tags), enumMember.getComments()));
     }
 
+    private RestApplicationModel enrichRestApplication(RestApplicationModel restApplicationModel) {
+        final List<RestMethodModel> enrichedRestMethods = new ArrayList<>();
+        for (RestMethodModel restMethod : restApplicationModel.getMethods()) {
+            final RestMethodModel enrichedRestMethod = enrichRestMethod(restMethod);
+            enrichedRestMethods.add(enrichedRestMethod);
+        }
+        return restApplicationModel.withMethods(enrichedRestMethods);
+    }
+
+    private RestMethodModel enrichRestMethod(RestMethodModel method) {
+        final Method dMethod = findJavadocMethod(method.getOriginClass(), method.getName(), dRoots);
+        return dMethod != null
+                ? method.withComments(getComments(dMethod.getComment(), dMethod.getTag()))
+                : method;
+    }
+
     // finders
 
+    private static Method findJavadocMethod(java.lang.Class<?> cls, String name, List<Root> dRoots) {
+        final Class dClass = findJavadocClass(cls, dRoots);
+        final Interface dInterface = findJavadocInterface(cls, dRoots);
+        if (dClass != null) {
+            return findJavadocMethod(name, dClass.getMethod());
+        } else if (dInterface != null) {
+            return findJavadocMethod(name, dInterface.getMethod());
+        } else {
+            return null;
+        }
+    }
+
     private static Class findJavadocClass(java.lang.Class<?> cls, List<Root> dRoots) {
         final String name = cls.getName().replace('$', '.');
         for (Root dRoot : dRoots) {

typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/MethodModel.java

@@ -8,11 +8,11 @@
 
 public class MethodModel {
 
-    private final Class<?> originClass;
-    private final String name;
-    private final List<MethodParameterModel> parameters;
-    private final Type returnType;
-    private final List<String> comments;
+    protected final Class<?> originClass;
+    protected final String name;
+    protected final List<MethodParameterModel> parameters;
+    protected final Type returnType;
+    protected final List<String> comments;
 
     public MethodModel(Class<?> originClass, String name, List<MethodParameterModel> parameters, Type returnType, List<String> comments) {
         this.originClass = originClass;
@@ -42,4 +42,8 @@ public List<String> getComments() {
         return comments;
     }
 
+    public MethodModel withComments(List<String> comments) {
+        return new MethodModel(originClass, name, parameters, returnType, comments);
+    }
+
 }

typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/RestApplicationModel.java

@@ -3,17 +3,26 @@
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Objects;
 
 
 public class RestApplicationModel {
 
     private final RestApplicationType type;
     private String applicationPath;
     private String applicationName;
-    private final List<RestMethodModel> methods = new ArrayList<>();
+    private final List<RestMethodModel> methods;
 
     public RestApplicationModel(RestApplicationType type) {
         this.type = type;
+        this.methods = new ArrayList<>();
+    }
+
+    public RestApplicationModel(RestApplicationType type, String applicationPath, String applicationName, List<RestMethodModel> methods) {
+        this.type = Objects.requireNonNull(type);
+        this.applicationPath = applicationPath;
+        this.applicationName = applicationName;
+        this.methods = Objects.requireNonNull(methods);
     }
 
     public RestApplicationType getType() {
@@ -40,4 +49,8 @@ public List<RestMethodModel> getMethods() {
         return methods;
     }
 
+    public RestApplicationModel withMethods(List<RestMethodModel> methods) {
+        return new RestApplicationModel(type, applicationPath, applicationName, methods);
+    }
+
 }

typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/RestMethodModel.java

@@ -50,4 +50,9 @@ public MethodParameterModel getEntityParam() {
         return entityParam;
     }
 
+    @Override
+    public RestMethodModel withComments(List<String> comments) {
+        return new RestMethodModel(originClass, name, returnType, rootResource, httpMethod, path, pathParams, queryParams, entityParam, comments);
+    }
+
 }

typescript-generator-core/src/test/java/cz/habarta/typescript/generator/JaxrsApplicationTest.java

@@ -436,6 +436,16 @@ public void testNamespacingByAnnotation() {
         Assert.assertTrue(errorMessage, !output.contains("class PersonResourceClient"));
     }
 
+    @Test
+    public void testJavadoc() {
+        final Settings settings = TestUtils.settings();
+        settings.outputFileType = TypeScriptFileType.implementationFile;
+        settings.generateJaxrsApplicationInterface = true;
+        settings.javadocXmlFiles = Arrays.asList(new File("target/test-javadoc.xml"));
+        final String output = new TypeScriptGenerator(settings).generateTypeScript(Input.from(OrganizationApplication.class));
+        Assert.assertTrue(output.contains("Returns person with specified ID."));
+    }
+
     @ApplicationPath("api")
     public static class OrganizationApplication extends Application {
         @Override
@@ -480,6 +490,9 @@ public static class Organization {
     public static class PersonResource {
         @PathParam("personId")
         protected long personId;
+        /**
+         * Returns person with specified ID.
+         */
         @GET
         public Person getPerson() {
             return null;