Getting rid of surprise spacing with <pre>

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Getting rid of surprise spacing with <pre>

Paul Benedict-2
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?

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.

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
Reply | Threaded
Open this post in threaded view
|

Re: 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

Reply | Threaded
Open this post in threaded view
|

Re: Getting rid of surprise spacing with <pre>

Paul Benedict-2


Cheers,
Paul

On Mon, Aug 1, 2016 at 12:13 PM, Jonathan Gibbons <[hidden email]> 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.

 

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.


Reply | Threaded
Open this post in threaded view
|

Re: 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 <[hidden email]> 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