Getting rid of surprise spacing with <pre>

[Paul Benedict]

Cheers,
Paul

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



>
>> 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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20160801/12a6f2d7/attachment-0001.html>