Docs generated from javadoc get mangled when using html tags or taglets (like link, code)

[simonbasle]

Consider the following javadoc:

/**
 * This {@link DocumentedMeter} is about {@link MyClass my class}.
 * <p>
 * It uses a {@code status} tag.
 */

Which seems to produce the following kind of output:

This is about . It uses a tag.

Currently the tool uses Roaster's getJavadoc().getText() method, which strips the taglets and seems also to strip the html tags from the returned String.

Perhaps getJavadoc().getFullText() would be a better alternative, but then we have to consider HTML and taglets in the asciidoc output :/

Option 1: naive sanitization to HTML

One way of doing basic sanitization would be to:

1. use getFullText()
2. search for opening of taglets {@xxx and replace with an opening code tag <code>
3. search for closing taglet bracket } and replace by a closing code tag </code>
4. append that to the asciidoc as unprocessed HTML within a ++++ block

Drawback: this is incompatible with asciidoctor-pdf generation.

Option 2: naive sanitization to Asciidoc

This implies more effort to convert a basic set of common HTML tags to asciidoc. I'd consider p, br for a start.
For taglets, I'd consider @link and @code as the minimum viable set.

1. use getFullText()
2. convert <p> to double newline, remove </p>
3. convert <br>/<br/> to newline
4. convert {@code xxx} to `xxx`
5. convert {@link xxx} to `xxx` too (not super reliable especially with links + description, but eh)
6. append that naive asciidoc conversion to the result

[simonbasle]

other html tags to consider: ul, ol, li (tricky, as li translation depends on the enclosing ul vs ol)