therapi-runtime-javadoc icon indicating copy to clipboard operation
therapi-runtime-javadoc copied to clipboard

Problem with JavadocParser.parseParam with formatted javadoc in a method (identations)

Open asiercamara opened this issue 1 year ago • 0 comments

I have encountered an issue with the Javadoc of the methods and their parameters after formatting them in Eclipse and adjusting their indentations.

Let me explain with code examples

Before format

/**
 * @param param1 first paramater
 * @param param2 second paramater
 * @return the data 
 */
@GetMapping(value = "/example/{param1}/{param2}")
public String example (@PathVariable String param1, @PathVariable String param2) {
	return "ok";
}

After formatting the code, the javadoc is aligned for easier readability (look at the two spaces between @param and the params names)

/**
 * @param  param1 first paramater
 * @param  param2 second paramater
 * @return        the data
 */
@GetMapping(value = "/example/{param1}/{param2}")
public String example(@PathVariable String param1, @PathVariable String param2) {

	return "ok";
}

The problem is that the comments for the parameters are lost due to such indentation

In the class com.github.therapi.runtimejavadoc.internal.parser.JavadocParser we have this method

private static ParamJavadoc parseParam(BlockTag t, String owningClass) {
	String[] paramNameAndComment = whitespace.split(t.value, 2);
	String paramName = paramNameAndComment[0];
	String paramComment = paramNameAndComment.length == 1 ? "" : paramNameAndComment[1];

	return new ParamJavadoc(paramName, CommentParser.parse(owningClass, paramComment));
}

When this method is called, we got this

t	BlockTag  (id=172)	
	name	"param" (id=199)	
	value	" param1 first paramater" (id=200)	
paramName	"" (id=173)	
paramComment	"param1 first paramater" (id=184)	

paramName is empty string

After patch the method and trimming t.value here whitespace.split(t.value.trim(), 2);, seems to solve the problem

t	BlockTag  (id=171)	
	name	"param" (id=199)	
	value	" param1 first paramater" (id=200)	
paramName	"param1" (id=182)	
paramComment	"first paramater" (id=173)	

"Is it possible to add this solution to the project or something similar?

Method with the "patch"

private static ParamJavadoc parseParam(BlockTag t, String owningClass) {
	String[] paramNameAndComment = whitespace.split(t.value.trim(), 2);
	String paramName = paramNameAndComment[0];
	String paramComment = paramNameAndComment.length == 1 ? "" : paramNameAndComment[1];

	return new ParamJavadoc(paramName, CommentParser.parse(owningClass, paramComment));
}

Thank you very much for your time

asiercamara avatar Dec 14 '23 10:12 asiercamara