search

ScaCap / spring-auto-restdocs

Spring Auto REST Docs is an extension to Spring REST Docs
https://scacap.github.io/spring-auto-restdocs/
Apache License 2.0
310 stars 86 forks source link

@see javadoc support #161

Closed jvmlet closed 6 years ago

jvmlet commented 6 years ago

Hi, first of all thanks for the great tool. I have issue with the field documentation annotated with @see :

/**
 *
*  @see <a href="https://github.com/jirutka/rsql-parser">this for the syntax</a>
*/
    private String rsqlFilter;

The description is being rendered literally as See &lt;a href="https://github.com/jirutka/rsql-parser"&gt;this for the syntax&lt;/a&gt;. i.e. the < and > characters are escaped, causing the text to be rendered as-is and not as HTML tags. Please do not escape the HTML entities where applicable. Thanks

fbenz commented 6 years ago

I see a few options here:

  1. Ensuring that AsciiDoctor does not interpret the text and takes it literally. This can be done with an inline pass macro, see http://asciidoctor.org/docs/asciidoc-writers-guide/#inline-pass-macro-and-explicit-substitutions. However, this only works if HTML is generated out of AsciiDoc and would fail for other formats like PDF.
  2. Transform Javadoc HTML to AsciiDoc / Markdown. We already do this for a few things. Supporting everything would be quite a bit of work and error prone. I quick search revealed no Java library that already does this.
  3. Write the Javadoc in AsciiDoc (or Markdown) and not HTML. If the Javadoc is just used for the REST API documentation, this should be fine. But this is not possible if Javadoc is also used to generate other documentation.

Option 3 is already supported. Option 1 might be easy to support, but we have not experimented with it yet. If we add support for option 1, we should make it configurable so that one can choose between option 1 (new) and option 2/3 (now).

Option 3 might work in your case, but I assume that you would prefer option 1, or?