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

Add support for JavaDoc tags #409

Closed synFK closed 9 months ago

synFK commented 4 years ago

When the JavaDoc is extracted from source and it comes to a JavaDoc tag like {@code} or {@link} they are simply ignored and not translated at all. The HTML equivalent <code> works fine (while <a href="..."> does not).

jmisur commented 4 years ago

Can you provide an actual example where these JavaDoc tags would be useful in terms of API documentation?

fbenz commented 4 years ago

We actually have a case in our examples: https://github.com/ScaCap/spring-auto-restdocs/blob/d658385692437e5ffe110e3f274f4388c2fefaa2/samples/java-webmvc/src/main/java/capital/scalable/restdocs/example/items/ItemResource.java#L116 but there we use <code> and not {@code}. The result is

image

We also recently added support for code tags in our Dokka extension and also added this to the Kotlin example: https://github.com/ScaCap/spring-auto-restdocs/pull/387 It can be useful if you have code fragments in the documentation or just want to highlight something. Dokka supports both Javadoc and KDoc and thus with using the Dokka extension instead of the doclet it should work with {@code}.

Code tags shouldn't be hard to support in the doclet but links might be tricky. Contributions are welcome.

fbenz commented 4 years ago

I just discovered that this feature has been requested already https://github.com/ScaCap/spring-auto-restdocs/issues/346 and a PR has been started as well https://github.com/ScaCap/spring-auto-restdocs/pull/390 but never finished. We could pick this up again.

The license header issue has been fixed in the meantime.