As part of the goals of this tool we are trying to also have documentation for the TypeScript generated from the Java JsTypes. Annotation processors didn't help us in doing so: the annotation processor API is limited when it comes to read and parse the JavaDocs from the Java source elements, and only copies the Javadoc string from the Java Element as is and put it on the generated TypeScript members.
However, when processed by any TypeScript doc tool, those JavaDoc tags end up rendered poorly. Instead, we need to transform those Javadoc tags into their TypeScript analog, taking care to also transform Java type references into TypeScript references, and @code snippets into backticks.
This patch uses Javadoc tools to actually generate the TypeScript as Doclets have a better API to actually parse the Javadocs and transform them into a TypeScript docs, while still providing access to the Elements and Mirrors that the annotation processor side needs. We are keeping the processor and refactoring the code to actually share the APIs that generated the TypeScript definitions between the annotation processor and the doclet while letting each handle the docs on its own, so for now the doclet will generate better TypeScript docs than the processor, and will correctly transform links and code tags from JavaDocs.
vegegoku
commented
1 year ago
As part of the goals of this tool we are trying to also have documentation for the TypeScript generated from the Java JsTypes. Annotation processors didn't help us in doing so: the annotation processor API is limited when it comes to read and parse the JavaDocs from the Java source elements, and only copies the Javadoc string from the Java Element as is and put it on the generated TypeScript members.
However, when processed by any TypeScript doc tool, those JavaDoc tags end up rendered poorly. Instead, we need to transform those Javadoc tags into their TypeScript analog, taking care to also transform Java type references into TypeScript references, and
@codesnippets into backticks.This patch uses Javadoc tools to actually generate the TypeScript as Doclets have a better API to actually parse the Javadocs and transform them into a TypeScript docs, while still providing access to the Elements and Mirrors that the annotation processor side needs. We are keeping the processor and refactoring the code to actually share the APIs that generated the TypeScript definitions between the annotation processor and the doclet while letting each handle the docs on its own, so for now the doclet will generate better TypeScript docs than the processor, and will correctly transform links and code tags from JavaDocs.
Fix #80