Discussion: how to deal with javadoc-link tags

[magicDGS]

A javadoc could have several the @see and the @link tags to point to specific classes/method. Because the javadoc is used for developer consumption and in the case of Barclay for help-pages generation, this introduces problems when writing the javadoc thinking in both use cases. This is an example class to evaluate the possible problems:

/**
 * Description in javadoc. 
 * This class may be related with {@link SecondDocumentedFeature}, so check its documentation.
 *
 * @see ThirdDocumentedFeature
 * @see FourthDocumentedFeature
 * @see UndocumentedFeature
 */
@DocumentedFeature(extraDocs = FourthDocumentedFeature.class)
public class FirstDocumentedFeature {
    ...
}

The problems that may arise from this class in the help pages are the following:

• There is no way to access the SecondDocumentedFeature or the ThirdDocumentedFeature while parsing the FreeMarker templates. Even if they are documented and they have a link in the help pages. It will be ideal to populate this classes into the extraDocs.
• In the case that the @see classes are populated, there will be a clash in the FourthDocumentedFeature; in addition, the UndocumentedFeature does not have any entry in the help pages.
• The populated description from the javadoc is "Description in javadoc. This class may be related with {@link SecondDocumentedFeature}, so check its documentation.", which is confusing for a non-programer user. It will be ideal to parse the javadoc with Barclay and substitute this tag by the url.
• In the case that the @link tag is parsed: should the url be formatted as HTML or Markdown? What will happen with @link tags for non-documented features?

My suggestions, in order of preference, are the following:

1. Populate @see and @link tags into the extraDocs, not allowing classes with the same name (this is already constrained for tool names). Then, the parsing on in-line tags will be done by FreeMarker using a custom macro (I would like to have a macro file in Barclay containing this and other "common" functionality).
2. Remove all in-line tags by Barclay on output and do not take into account the @see tag. This will require that the FreeMarker template look for matching strings with the extraDocs and apply the link. If someone wants the @see tag, they could use a custom binding. This will keep the developer/user help completely separate, but it will complicate things in the template.
3. Parse the @link tags with Barclay and set the URL for documented features either as HTML or Markdown, by setting an option. This introduces a constraint in template outputs, because they will be expected to be encoded as HTML or Markdown.

[cmnbroad]

@magicDGS Thanks for writing this up. I'm still a bit unclear on the details of the proposed solutions, but in general, I don't think Barclay should be putting anything in the Freemarker property map that requires parsing/macros, or that is already formatted as html or markdown, if we can at all avoid it.

My proposal would be that we consider a simple enhancement to Barclay that recognizes @see or @link tags that reference documented features, and adds the corresponding file name to extraDocs just like any other extraDoc, so they require no post-processing. Any more advanced transformation should be left to custom doclet code, since it has access to the ClassDoc object and thus all of the embedded tags.

[magicDGS]

Your proposal is actually the one that I suggest in the first point. But that proposal also includes an addition of a macro file with optional methods to use in the FreeMarker templates. Just looking at the example class, the description in the JSON will be: Description in javadoc.\nThis class may be related with {@link SecondDocumentedFeature}, so check its documentation.

For a normal user, the {@link SecondDocumentedFeature} does not have any meaning. My suggestion is to provide in the Barclay templates a file with common macros to parse this and substitute any {@link ClassName} using the extraDocs information (which will contain this class if we populate it with your suggestion).

Anyway, I think that we agree on the inclusion of @see and @link tags in the extraDocs. I can do a PR for that purpose as soon as you give me your OK.