Embedded tags in javadoc are not rendered correctly in either javadoc or gatkdoc.

[cmnbroad]

Original report by @samuelklee (see broadinstitute/barclay#189):

I noticed that Javadoc @value tags are not being rendered correctly in e.g. https://gatk.broadinstitute.org/hc/en-us/articles/9570326304155-ScoreVariantAnnotations-BETA-. I used these tags to specify the variables corresponding to argument names (e.g., StandardArgumentDefinitions#INTERVALS_LONG_NAME instead of intervals , USE_ALLELE_SPECIFIC_ANNOTATIONS_LONG_NAME instead of use-allele-specific-annotations, etc.), and while they show up correctly when rendering the Javadoc within IntelliJ, it seems the same is not true on the GATK website. Is there an easy fix in the code for generating these docs, or should I just avoid using this tag?

My original response:

I tested this using the new Java 17 doclets in the hope that it would just work, but the result is the same. However, the new Java language model classes make it easy to interpolate these, so I’ll fix this in the barclay Java 17 branch.

However, in looking more closely, it's not as easy to fix as I first thought, and the problem is a little deeper than I first realized. Although it's easy to detect these using the new Java 17 apis, it's more difficult to retrieve the actual values. And even then, because the gatkdoc process only consumes a subset of the classes consumed by the javadoc process (it only sees @DocumentedFeatures), it's quite easy to reference something in the javadoc comment that can be resolved by javdoc, but not by gatkdoc.

But it appears that even the javadoc process isn't rendering these tags correctly. Here is the raw javadoc comment:

 *         Input VCF file. Site-level annotations will be extracted from the contained variants (or alleles,
 *         if the {@value USE_ALLELE_SPECIFIC_ANNOTATIONS_LONG_NAME} argument is specified).

The rendering in javadoc (the argument name is missing entirely, but it should be interpolated):

The rendering in gatkdoc (the variable name appears in the text, but it should be interpolated):

Note that QuickDocumentation within IntelliJ seems to render them correctly.

Additionally, I noticed that some {@link} targets are not rendering correctly in gatkdoc, i.e., these links in ScoreVariantAnnotations:

*     {@link VariantRecalibrator} workflow. Using a previously trained model produced by {@link TrainVariantAnnotationsModel},

work in javadoc, but not gatkDoc, even though the target in this case IS included in the set of objects available to the gatkDoc process. The gatkdoc process is not translating these (and apparently its replacing them with the text). But generating the anchor tags will require translation because the javadoc output files are organized hierarchically whereas the gatkdoc files are flat.

The links in html file generated by javadoc have anchor tags with proper hrefs, whereas the html generated by gatkDoc has only the plain text (no anchors - the links are removed and replaced with the text by gatkdoc).

Even if we embedded the javadoc in with the gatkdoc, we still would have to translate some links for gatkdoc targets at doc generation time, because when a user views the gatkdoc for ScoreVariants, we want the link to VariantRecalibrator to go to the VariantRecalibrator page from gatkdoc, not the page from javadoc. Also, for any entities for which there is no gatkdoc (i.e., a method reference), the gatkdoc page would be referencing javadoc page, which would be jarring for the user.

Some of these issues are bugs, but there is an inherent difficulty in using javadoc for the user doc, since the writer has to be cognizant of the differences in the audience and environments.

[samuelklee]

Any chance of this getting fixed? Otherwise I will go back and clean up the use of the @value tag in the GATK VETS docs (and maybe elsewhere) in #8131.

OTOH, I’m a little hesitant to clean up e.g. @link and @code tags. Hopefully these will be more easily addressable, especially the latter?