On 08/01/2016 11:17 AM, Paul Benedict wrote:
Cheers,
Paul
On Mon, Aug 1, 2016 at 12:13 PM, Jonathan Gibbons
<[email protected] <mailto:[email protected]>> wrote:
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.
What significant change are you referring to? All it would do would
eliminate a line break. I don't consider that significant. It's just
white-space at the beginning or the end.
What if people have already written comments that take that line-break
into account?
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.
Javadoc already ignores the asterisk. It's sensible to also ignore the
first space since both characters belong to the standard way of doing
comments. To your question of wanting more spaces, people would still
have that option. My proposal isn't to eliminate all spaces here, just
the first since that's clearly belonging to the format of Javadoc --
not the preformatted text itself.
javadoc is defined to ignore leading white space, followed by asterisk
characters. See
https://docs.oracle.com/javase/8/docs/api/javax/lang/model/util/Elements.html#getDocComment-javax.lang.model.element.Element-
for a more complete description.
In particular, it is not specified to ignore any whitespace after the
asterisks, however conventional they might be.
The bottom line is that whitespace within <pre> is a difficult issue,
whether it is leading and trailing newlines, or leading whitespace on
each libe, and changing the rules always affects/annoys someone. As I
said, I think the only way out of this is to define a new tag with
well-defined semantics, and then to stick with those semantics.
-- Jon
