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
