Note that this ticket is assuming the use of typedoc to generate HTML from generated TS files.
Presently the annotation-processor implementation of this project copies javadoc strings directly into typescript doc strings, with no additional transformations, which has a few side effects.
{@link ...} tags use the Java packages and names, and often cannot be resolved in typescript due to different namespaces and names
{@code ...} doesn't exist at all in typescript - backticks are the usual wrapper around the code snippet
Unescaped HTML is not parsed and closed by typedoc at the end of a comment, which can break other content on the same page. A quick pass with something like jsoup could fix this (not as important as the other items)
Other tags we might want to support can be found at https://typedoc.org/guides/tags/. For many of these, we could either just have the Java author write the tag directly in javadoc, or possibly support explicit annotations (especially for the marker tags, like @enum or @experimental. @ignore, @hidden, @internal would be good too? For others, we might want a specific javadoc syntax, like @privateRemarks, or @example.
To implement this, an annotation processor probably is no longer appropriate, since that API doesn't seem to have the features we need to parse the javadoc into elements and let us do any walking/rewriting. However, the Javadoc api itself now (as of Java 9+) supports Elements, so can run the same code written for the annotation processor, and then also process each doc string as needed.
Proposed changes:
[ ] Refactor existing "element+mirror -> d.ts writer" into its own module, so that the existing processor module is only the annotation processor used to generate a simple .d.ts file. Remove the ability for this to copy any tsdoc except for very simple annotations as may be needed (such as @deprecated?). This processor may still be helpful for projects to typecheck without generating any docs, just by running the compiler, and omitting other doc strings should make it clear that this is not the way to get clean doc output. This method of writing perhaps should also write a comment at the top of the file that it only contains type information, and no documentation.
[ ] Add a new doclet module, which would both run the existing writer, but also transform javadoc into ts doc strings. The first pass is probably only concerned with @link and @code.
[ ] Expand support for ts doc string annotations. Perhaps create a @TsDocAnnotation that takes a string, and can be put on an annotation type to indicate that it should only be included in the doc string for the given member (for example @TsBeta or @TsEvent annotations could easily be created that do nothing except declare the required ts doc annotation).
[ ] Sanity check the generated output to guard against broken content where other incompatibilities are found between ts doc and javadoc (such as unclosed tags)
[ ] Example project showing how to also run typedoc
Note that this ticket is assuming the use of typedoc to generate HTML from generated TS files.
Presently the annotation-processor implementation of this project copies javadoc strings directly into typescript doc strings, with no additional transformations, which has a few side effects.
{@link ...}tags use the Java packages and names, and often cannot be resolved in typescript due to different namespaces and names{@code ...}doesn't exist at all in typescript - backticks are the usual wrapper around the code snippetOther tags we might want to support can be found at https://typedoc.org/guides/tags/. For many of these, we could either just have the Java author write the tag directly in javadoc, or possibly support explicit annotations (especially for the marker tags, like
@enumor@experimental.@ignore,@hidden,@internalwould be good too? For others, we might want a specific javadoc syntax, like@privateRemarks, or@example.To implement this, an annotation processor probably is no longer appropriate, since that API doesn't seem to have the features we need to parse the javadoc into elements and let us do any walking/rewriting. However, the Javadoc api itself now (as of Java 9+) supports Elements, so can run the same code written for the annotation processor, and then also process each doc string as needed.
Proposed changes:
@deprecated?). This processor may still be helpful for projects to typecheck without generating any docs, just by running the compiler, and omitting other doc strings should make it clear that this is not the way to get clean doc output. This method of writing perhaps should also write a comment at the top of the file that it only contains type information, and no documentation.@linkand@code.@TsDocAnnotationthat takes a string, and can be put on an annotation type to indicate that it should only be included in the doc string for the given member (for example@TsBetaor@TsEventannotations could easily be created that do nothing except declare the required ts doc annotation).