Getting rid of surprise spacing with <pre>

[Jonathan Gibbons]

On 08/01/2016 11:17 AM, Paul Benedict wrote:
>
>
> Cheers,
> Paul
>
> On Mon, Aug 1, 2016 at 12:13 PM, Jonathan Gibbons 
> <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20160801/c42ba7d6/attachment.html>