ScaCap
Multi-line text for block tags
Is there a way to prevent multi-line block tags from being partially interpreted as a part of the method description? As a sanity check, I easily reproduced this issue using java-webmvc sample project.
Project properties:
<java.version>11</java.version>
<spring-restdocs.version>2.0.4.RELEASE</spring-restdocs.version>
<spring-auto-restdocs.version>2.0.9</spring-auto-restdocs.version>
ItemResource#getItem:
/**
* Returns item by ID.
* <p>
* An example of returning a custom response type and custom exception with response status.
*
* @param id ID of the item. If this block tag description extends
* to another line, any text beyond the first line is concatenated to the description.
* @return response
*
* @deprecated This also occurs here if this
* other line extends to another line.
*/
@GetMapping("{id}")
public ResponseEntity<Void> getItem(@PathVariable("id") String id) {
return ResponseEntity.ok().build();
}
Resulting description (Notice the last 2 sentences in bold are from the multi-line block tags):
Deprecated. This also occurs here if this other line extends to another line. Returns item by ID. An example of returning a custom response type and custom exception with response status. to another line, any text beyond the first line is concatenated to the description. other line extends to another line.
Doclet processor for jdk9+ indeed does something weird here. We'll look into it.
Hey! Any progress here? Our current quick-fix is to use the jdk8 doclet. :) Again I am willing to help if needed.
