WIP: open-api: parse javadoc

- Java APT can't be used to read doc bc we use byte code analysis
- Use checkstyle for getting doc
- This feature will be only for Java code base (not available on Kotlin)
- ref #3729

Author: jknack

.gitignore

@@ -28,7 +28,6 @@ TODO
 .interp
 tmp
 checkstyle
-javadoc
 *.mv.db
 versions
 out

modules/jooby-openapi/pom.xml

@@ -64,6 +64,12 @@
       <artifactId>swagger-models</artifactId>
     </dependency>
 
+    <dependency>
+      <groupId>com.puppycrawl.tools</groupId>
+      <artifactId>checkstyle</artifactId>
+      <version>10.26.1</version>
+    </dependency>
+
     <dependency>
       <groupId>commons-codec</groupId>
       <artifactId>commons-codec</artifactId>
@@ -134,13 +140,6 @@
       <version>1.17.6</version>
       <scope>test</scope>
     </dependency>
-
-    <dependency>
-      <groupId>com.puppycrawl.tools</groupId>
-      <artifactId>checkstyle</artifactId>
-      <version>10.26.1</version>
-      <scope>test</scope>
-    </dependency>
   </dependencies>
 
   <build>

modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/ClassDoc.java

@@ -0,0 +1,91 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package io.jooby.internal.openapi.javadoc;
+
+import static io.jooby.internal.openapi.javadoc.JavaDocSupport.*;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.stream.Collectors;
+
+import com.puppycrawl.tools.checkstyle.api.DetailAST;
+import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes;
+import com.puppycrawl.tools.checkstyle.api.TokenTypes;
+
+public class ClassDoc extends JavaDocNode {
+
+  private final DetailAST node;
+  private List<MethodDoc> methods = new ArrayList<>();
+
+  public ClassDoc(DetailAST node, DetailAST javaDoc) {
+    super(javaDoc);
+    this.node = node;
+  }
+
+  public void addMethod(MethodDoc method) {
+    this.methods.add(method);
+  }
+
+  public String getSummary() {
+    var text = new StringBuilder();
+    for (var node : forward(javadoc, STOP_TOKENS).toList()) {
+      if (node.getType() == JavadocTokenTypes.NEWLINE && !text.isEmpty()) {
+        break;
+      } else if (node.getType() == JavadocTokenTypes.TEXT) {
+        text.append(node.getText());
+      }
+    }
+    return text.isEmpty() ? getText().trim() : text.toString().trim();
+  }
+
+  public String getDescription() {
+    var text = getText();
+    var summary = getSummary();
+    return summary.equals(text) ? "" : text.replaceAll(summary, "").trim();
+  }
+
+  public Optional<MethodDoc> getMethod(String name, List<String> parameterNames) {
+    var filtered = methods.stream().filter(it -> it.getName().equals(name)).toList();
+    if (filtered.isEmpty()) {
+      return Optional.empty();
+    }
+    if (filtered.size() == 1) {
+      return Optional.of(filtered.get(0));
+    }
+    return filtered.stream()
+        .filter(it -> it.getParameterNames().equals(parameterNames))
+        .findFirst();
+  }
+
+  public String getSimpleName() {
+    return node.findFirstToken(TokenTypes.IDENT).getText();
+  }
+
+  public String getName() {
+    return forward(node.getParent())
+            .filter(tokens(TokenTypes.PACKAGE_DEF))
+            .map(
+                it ->
+                    tree(it)
+                        .filter(tokens(TokenTypes.DOT, TokenTypes.IDENT))
+                        .findFirst()
+                        .orElse(null))
+            .filter(Objects::nonNull)
+            .flatMap(
+                it ->
+                    tree(it)
+                        .filter(tokens(TokenTypes.DOT, TokenTypes.SEMI).negate())
+                        .map(DetailAST::getText))
+            .collect(Collectors.joining(".", "", "."))
+        + getSimpleName();
+  }
+
+  public List<MethodDoc> getMethods() {
+    return methods;
+  }
+}

modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/JavaDocNode.java

@@ -0,0 +1,54 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package io.jooby.internal.openapi.javadoc;
+
+import java.util.List;
+import java.util.Set;
+
+import com.puppycrawl.tools.checkstyle.DetailNodeTreeStringPrinter;
+import com.puppycrawl.tools.checkstyle.JavadocDetailNodeParser;
+import com.puppycrawl.tools.checkstyle.api.DetailAST;
+import com.puppycrawl.tools.checkstyle.api.DetailNode;
+import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes;
+import com.puppycrawl.tools.checkstyle.utils.JavadocUtil;
+
+public class JavaDocNode {
+  protected final DetailNode javadoc;
+  protected static final Set<Integer> STOP_TOKENS = Set.of(JavadocTokenTypes.JAVADOC_TAG);
+
+  public JavaDocNode(DetailAST node) {
+    this.javadoc = new JavadocDetailNodeParser().parseJavadocAsDetailNode(node).getTree();
+  }
+
+  public String getText() {
+    return getText(JavaDocSupport.forward(javadoc, STOP_TOKENS).toList(), false);
+  }
+
+  protected String getText(List<DetailNode> nodes, boolean stripLeading) {
+    var builder = new StringBuilder();
+    for (var node : nodes) {
+      if (node.getType() == JavadocTokenTypes.TEXT) {
+        var text = node.getText();
+        if (stripLeading && Character.isWhitespace(text.charAt(0))) {
+          builder.append(' ').append(text.stripLeading());
+        } else {
+          builder.append(text);
+        }
+      } else if (node.getType() == JavadocTokenTypes.NEWLINE) {
+        var next = JavadocUtil.getNextSibling(node);
+        if (next != null && next.getType() != JavadocTokenTypes.LEADING_ASTERISK) {
+          builder.append(next.getText());
+        }
+      }
+    }
+    return builder.toString().trim();
+  }
+
+  @Override
+  public String toString() {
+    return DetailNodeTreeStringPrinter.printTree(javadoc, "", "");
+  }
+}

modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/JavaDocParser.java

@@ -0,0 +1,61 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package io.jooby.internal.openapi.javadoc;
+
+import static io.jooby.internal.openapi.javadoc.JavaDocSupport.backward;
+import static io.jooby.internal.openapi.javadoc.JavaDocSupport.tokens;
+
+import java.io.IOException;
+import java.nio.file.Path;
+import java.util.Optional;
+
+import com.puppycrawl.tools.checkstyle.JavaParser;
+import com.puppycrawl.tools.checkstyle.api.CheckstyleException;
+import com.puppycrawl.tools.checkstyle.api.DetailAST;
+import com.puppycrawl.tools.checkstyle.api.TokenTypes;
+
+public class JavaDocParser {
+
+  public static Optional<ClassDoc> parse(Path filePath) throws CheckstyleException, IOException {
+    ClassDoc result = null;
+    var tree = JavaParser.parseFile(filePath.toFile(), JavaParser.Options.WITH_COMMENTS);
+    for (var comment :
+        JavaDocSupport.forward(tree).filter(tokens(TokenTypes.COMMENT_CONTENT)).toList()) {
+      var nodePath = path(comment);
+      // ensure class
+      if (result == null) {
+        result = new ClassDoc(nodePath[1], comment.getParent());
+      }
+      if (nodePath[nodePath.length - 1] != null) {
+        // there is a method here
+        var method = new MethodDoc(nodePath[nodePath.length - 1], comment.getParent());
+        result.addMethod(method);
+      }
+    }
+    return Optional.ofNullable(result);
+  }
+
+  private static DetailAST[] path(DetailAST comment) {
+    var classDef =
+        backward(comment)
+            .filter(
+                tokens(
+                    TokenTypes.ENUM_DEF,
+                    TokenTypes.CLASS_DEF,
+                    TokenTypes.INTERFACE_DEF,
+                    TokenTypes.RECORD_DEF))
+            .findFirst()
+            .orElseThrow(() -> new IllegalStateException("no type found"));
+    var packageDef =
+        JavaDocSupport.forward(classDef.getParent())
+            .filter(tokens(TokenTypes.PACKAGE_DEF))
+            .findFirst()
+            .orElse(null);
+    var methodDef =
+        backward(comment).filter(tokens(TokenTypes.METHOD_DEF)).findFirst().orElse(null);
+    return new DetailAST[] {packageDef, classDef, methodDef};
+  }
+}