Cherry pick commits from main branch to release/1.0 (#94)

Introduced a Doclet to allow for Javadoc->typedoc transformations.
Cleaned up a few other output details, in anticipation of another
release.

jsinterop-ts-defs-doclet/pom.xml

@@ -0,0 +1,118 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <artifactId>jsinterop-ts-defs</artifactId>
+        <groupId>com.vertispan.tsdefs</groupId>
+        <version>1.0.0-RC2</version>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>jsinterop-ts-defs-doclet</artifactId>
+    <packaging>jar</packaging>
+
+    <name>tsinterop-doclet</name>
+    <url>https://github.com/Vertispan/jsinterop-ts-defs</url>
+
+    <properties>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <project.build.outputEncoding>UTF-8</project.build.outputEncoding>
+
+        <maven.compiler.source>11</maven.compiler.source>
+        <maven.compiler.target>11</maven.compiler.target>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.vertispan.tsdefs</groupId>
+            <artifactId>jsinterop-ts-defs-impl</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>com.google.jsinterop</groupId>
+            <artifactId>jsinterop-annotations</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.google.jsinterop</groupId>
+            <artifactId>base</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.google.elemental2</groupId>
+            <artifactId>elemental2-core</artifactId>
+            <version>1.1.0</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.google.auto</groupId>
+            <artifactId>auto-common</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.google.auto.service</groupId>
+            <artifactId>auto-service</artifactId>
+            <version>1.0.1</version>
+        </dependency>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <!-- https://mvnrepository.com/artifact/com.google.testing.compile/compile-testing -->
+        <dependency>
+            <groupId>com.google.testing.compile</groupId>
+            <artifactId>compile-testing</artifactId>
+            <version>0.19</version>
+            <scope>test</scope>
+        </dependency>
+        <!-- https://mvnrepository.com/artifact/org.assertj/assertj-core -->
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <version>3.23.1</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-shade-plugin</artifactId>
+                <version>3.4.1</version>
+                <executions>
+                    <execution>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>shade</goal>
+                        </goals>
+                        <configuration>
+                            <artifactSet>
+                                <excludes>
+                                   <exclude>com.vertispan.tsdefs:jsinterop-ts-defs</exclude>
+                                    <exclude>com.google.jsinterop:*</exclude>
+                                    <exclude>javax.annotation:*</exclude>
+                                    <exclude>javax.validation:*</exclude>
+                                    <exclude>com.google.code.findbugs:jsr305</exclude>
+                                    <exclude>com.google.j2objc:j2objc-annotations</exclude>
+                                    <exclude>com.google.errorprone:error_prone_annotations</exclude>
+                                </excludes>
+                            </artifactSet>
+                            <relocations>
+                                <relocation>
+                                    <pattern>com.google</pattern>
+                                    <shadedPattern>com.vertispan.tsdefs.shaded.com.google</shadedPattern>
+                                </relocation>
+                                <relocation>
+                                    <pattern>org.checkerframework</pattern>
+                                    <shadedPattern>com.vertispan.tsdefs.shaded.org.checkerframework</shadedPattern>
+                                </relocation>
+                            </relocations>
+                            <transformers>
+                                <transformer
+                                        implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
+                            </transformers>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>

jsinterop-ts-defs-doclet/src/main/java/com/vertispan/tsdefs/doclet/DocletLogWrapper.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright © 2023 Vertispan
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.vertispan.tsdefs.doclet;
+
+import com.vertispan.tsdefs.impl.LogWrapper;
+import javax.lang.model.element.AnnotationMirror;
+import javax.lang.model.element.Element;
+import javax.tools.Diagnostic;
+import jdk.javadoc.doclet.Reporter;
+
+public class DocletLogWrapper implements LogWrapper {
+
+  private final Reporter reporter;
+
+  public DocletLogWrapper(Reporter reporter) {
+    this.reporter = reporter;
+  }
+
+  @Override
+  public void printMessage(Diagnostic.Kind kind, CharSequence msg) {
+    reporter.print(kind, String.valueOf(msg));
+  }
+
+  @Override
+  public void printMessage(Diagnostic.Kind kind, CharSequence msg, Element e) {
+    reporter.print(kind, e, String.valueOf(msg));
+  }
+
+  @Override
+  public void printMessage(Diagnostic.Kind kind, CharSequence msg, Element e, AnnotationMirror a) {
+    reporter.print(kind, e, String.valueOf(msg));
+  }
+}

jsinterop-ts-defs-doclet/src/main/java/com/vertispan/tsdefs/doclet/TsDocTreeVisitor.java

@@ -0,0 +1,174 @@
+/*
+ * Copyright © 2023 Vertispan
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.vertispan.tsdefs.doclet;
+
+import static java.util.Objects.nonNull;
+
+import com.sun.source.doctree.*;
+import com.sun.source.util.DocTreePath;
+import com.sun.source.util.DocTrees;
+import com.sun.source.util.SimpleDocTreeVisitor;
+import com.vertispan.tsdefs.impl.Formatting;
+import com.vertispan.tsdefs.impl.HasProcessorEnv;
+import com.vertispan.tsdefs.impl.builders.TsElement;
+import java.util.Optional;
+import java.util.stream.Collectors;
+import javax.lang.model.element.Element;
+import javax.lang.model.element.ElementKind;
+import jdk.javadoc.doclet.DocletEnvironment;
+
+public class TsDocTreeVisitor extends SimpleDocTreeVisitor<String, Element> {
+
+  private final HasProcessorEnv env;
+  private final DocletEnvironment docletEnv;
+
+  public TsDocTreeVisitor(HasProcessorEnv env, DocletEnvironment docletEnv) {
+    this.env = env;
+    this.docletEnv = docletEnv;
+  }
+
+  @Override
+  protected String defaultAction(DocTree node, Element element) {
+    return node.toString();
+  }
+
+  @Override
+  public String visitLink(LinkTree node, Element element) {
+    return "{@link "
+        + visit(node.getReference(), element)
+        + (node.getLabel().isEmpty() ? "" : formatLabel(String.valueOf(node.getLabel().get(0))))
+        + "}";
+  }
+
+  @Override
+  public String visitReference(ReferenceTree node, Element element) {
+    return getElementFromReference(node, element)
+        .map(
+            referencedElement -> {
+              if (ElementKind.METHOD == referencedElement.getKind()) {
+                TsElement tsElement = TsElement.of(element, env);
+                TsElement refTsElement = TsElement.of(referencedElement, env);
+                TsElement parentTsElement =
+                    TsElement.of(referencedElement.getEnclosingElement(), env);
+
+                String namespace = tsElement.getNamespace();
+                String refNamespace = refTsElement.getNamespace();
+                String parentNamespace = parentTsElement.getNamespace();
+
+                boolean isSetterOrGetter = refTsElement.isSetter() || refTsElement.isGetter();
+
+                String name =
+                    isSetterOrGetter
+                        ? Formatting.nonGetSetName(refTsElement.getName())
+                        : refTsElement.getName();
+                String parentName = parentTsElement.getName();
+                if (refNamespace.equals(parentNamespace)) {
+                  String fullName = refNamespace + "." + parentName + "." + name;
+                  return fullName
+                      .replace(namespace + ".", "")
+                      .replace(tsElement.getName() + ".", "");
+                } else {
+                  return refNamespace + "." + name;
+                }
+              }
+              return formatName(TsElement.of(referencedElement, env));
+            })
+        .orElse(node.getSignature());
+  }
+
+  private Optional<Element> getElementFromReference(DocTree node, Element element) {
+    DocTrees trees = docletEnv.getDocTrees();
+    final Element referencedElement =
+        trees.getElement(
+            new DocTreePath(
+                new DocTreePath(trees.getPath(element), trees.getDocCommentTree(element)), node));
+    return Optional.ofNullable(referencedElement);
+  }
+
+  public String formatName(TsElement tsElement) {
+    String namespace = tsElement.getNamespace();
+    String jsName = tsElement.getName();
+    return namespace.isEmpty() ? jsName : (namespace + "." + jsName);
+  }
+
+  private String formatLabel(String label) {
+    if (nonNull(label) && !label.trim().isEmpty()) {
+      return " | " + label;
+    }
+    return "";
+  }
+
+  @Override
+  public String visitSee(SeeTree node, Element element) {
+    return "@see "
+        + node.getReference().stream()
+            .map(
+                docTree ->
+                    getElementFromReference(docTree, element)
+                        .map(refElement -> "{@link " + docTree.accept(this, element) + "}")
+                        .orElse(docTree.accept(this, element)))
+            .collect(Collectors.joining());
+  }
+
+  @Override
+  public String visitDocComment(DocCommentTree node, Element element) {
+    String body =
+        node.getFullBody().stream()
+            .map(docTree -> visit(docTree, element))
+            .collect(Collectors.joining());
+    String tags =
+        node.getBlockTags().stream()
+            .map(tag -> " " + tag.accept(this, element))
+            .collect(Collectors.joining("\n"));
+    return " " + body + "\n" + tags;
+  }
+
+  @Override
+  public String visitLiteral(LiteralTree node, Element element) {
+    if (nonNull(node.getBody())) {
+      String body = node.getBody().getBody();
+      String wrap = "`";
+      if (body.contains(System.lineSeparator())) {
+        wrap = "```";
+      }
+      return wrap + node.getBody().getBody() + wrap;
+    }
+    return super.visitLiteral(node, element);
+  }
+
+  @Override
+  public String visitText(TextTree node, Element element) {
+    return node.getBody();
+  }
+
+  @Override
+  public String visitReturn(ReturnTree node, Element element) {
+    return "@return "
+        + node.getDescription().stream()
+            .map(docTree -> docTree.accept(this, element))
+            .collect(Collectors.joining());
+  }
+
+  @Override
+  public String visitParam(ParamTree node, Element element) {
+    return (node.isTypeParameter() ? "@typeParam " : "@param ")
+        + node.getName()
+        + " - "
+        + node.getDescription().stream()
+            .map(docTree -> docTree.accept(this, element))
+            .collect(Collectors.joining());
+  }
+}