Getting rid of surprise spacing with <pre>

[Jonathan Gibbons]

On 08/01/2016 09:17 AM, Paul Benedict wrote:
> Dear Javadoc experts, I have two requests. It's based on this example:
>
> /**
>  * Hello.
>  * <pre>
>  * public int foo() {
>  *     return 1;
>  * }
>  * </pre>
>  */
>
> I have some usability problems with the way Javadoc processes this code.
>
> 1) I understand <pre> is meant to retain formatting, but it's also too 
> literal with regards to how people want to express code samples. 
> Above, the use of <pre> and </pre> emits two new lines into the 
> Javadoc, but I do find that unnecessary. My intention here is to place 
> the tags outside of my code example so not to interfere with the way 
> it looks in source. Couldn't there be an enhancement that if <pre> and 
> </pre> are found as the only token after the asterisk/space 
> combination, it would prevent emitting the new line characters?

That would be a significant change, and what works for you would not 
work for others. Also note that you may well want to use 
<pre>{@literal... }</pre> to avoid issues with characters like < > & in 
your code.

>
> 2) The other annoyance is that the space in the asterisk/space 
> combination is outputted! That doesn't make sense to me one bit. If 
> the Javadoc processor sees one long unbroken left-handed stanza of 
> comment continuation, I think the space should be ignored. That's 
> clearly meant to be a proper comment margin by the developer but not 
> meant for the output.

Who is to say that only one space should be ignore in the 
"asterisk/space" combination? Other folk might indent the body of the 
comment by more than a single space.  Ultimately, I think the solution 
to this category of problem is going to have to be a new javadoc tag for 
multi-line embedded code with well defined white-space semantics, and 
let people opt-in to using the new tag when they are ready to do so.


>
> I am merely just trying to get the extra whitespace removed without 
> having to mangle the source example in my comments. It just seems 
> logical for Javadoc to take a more natural approach to the way code is 
> preformatted in comments.
>
> Thanks!
>
> Cheers,
> Paul