You are viewing a plain text version of this content. The canonical link for it is here.
Posted to oak-dev@jackrabbit.apache.org by Jukka Zitting <ju...@gmail.com> on 2013/04/03 16:46:16 UTC
The
javadoc antipatternHi,
A trivially minor, but long-standing annoyance of mine seems to be
creeping over from Jackrabbit to Oak:
For some reason people are using "<p/>" as a paragraph break in
Javadoc comments. That's wrong on many levels. Javadoc comments are in
HTML, not XHTML, so the self-closing "<p/>" is strictly speaking
invalid. And even if they were in XHTML, "<p/>" would indicate a
separate, empty paragraph instead starting a new paragraph. I have no
idea where this convention comes from.
So, if it's not too much to ask, use "<p>" instead of "<p/>" when
starting a new paragraph in javadoc. It'll make my inner perfectionist
feel better when browsing source code.
Thanks! :-)
BR,
Jukka Zitting
Re: The
javadoc antipattern
Posted by Tobias Bocanegra <tr...@apache.org>.
HTML in javadoc is sooo 1990's :-)
why not: https://code.google.com/p/markdown-doclet/
regards, toby
On Mon, Jun 16, 2014 at 9:29 AM, Jukka Zitting <ju...@gmail.com> wrote:
> Hi,
>
> [resurrecting an old thread, since it seems we still have some
> affected javadocs in Oak]
>
> On Wed, Apr 3, 2013 at 10:46 AM, Jukka Zitting <ju...@gmail.com> wrote:
>> A trivially minor, but long-standing annoyance of mine seems to be
>> creeping over from Jackrabbit to Oak:
>>
>> For some reason people are using "<p/>" as a paragraph break in
>> Javadoc comments. That's wrong on many levels. Javadoc comments are in
>> HTML, not XHTML, so the self-closing "<p/>" is strictly speaking
>> invalid. And even if they were in XHTML, "<p/>" would indicate a
>> separate, empty paragraph instead starting a new paragraph. I have no
>> idea where this convention comes from.
>>
>> So, if it's not too much to ask, use "<p>" instead of "<p/>" when
>> starting a new paragraph in javadoc. It'll make my inner perfectionist
>> feel better when browsing source code.
>
> Avoiding this anti-pattern will also prevent problems with Java 8,
> where the javadoc tool will by default refuse to accept such comments.
> See https://bugs.openjdk.java.net/browse/JDK-8020619.
>
> BR,
>
> Jukka Zitting
Re: The
javadoc antipattern
Posted by Tobias Bocanegra <tr...@apache.org>.
On Mon, Jun 16, 2014 at 12:04 PM, Julian Reschke <ju...@gmx.de> wrote:
> On 2014-06-16 18:29, Jukka Zitting wrote:
>>
>> Hi,
>>
>> [resurrecting an old thread, since it seems we still have some
>> affected javadocs in Oak]
>>
>> On Wed, Apr 3, 2013 at 10:46 AM, Jukka Zitting <ju...@gmail.com>
>> wrote:
>>>
>>> A trivially minor, but long-standing annoyance of mine seems to be
>>> creeping over from Jackrabbit to Oak:
>>>
>>> For some reason people are using "<p/>" as a paragraph break in
>>> Javadoc comments. That's wrong on many levels. Javadoc comments are in
>>> HTML, not XHTML, so the self-closing "<p/>" is strictly speaking
>>> invalid. And even if they were in XHTML, "<p/>" would indicate a
>>> separate, empty paragraph instead starting a new paragraph. I have no
>>> idea where this convention comes from.
>>>
>>> So, if it's not too much to ask, use "<p>" instead of "<p/>" when
>>> starting a new paragraph in javadoc. It'll make my inner perfectionist
>>> feel better when browsing source code.
>>
>>
>> Avoiding this anti-pattern will also prevent problems with Java 8,
>> where the javadoc tool will by default refuse to accept such comments.
>> See https://bugs.openjdk.java.net/browse/JDK-8020619.
>
>
> Maybe we should try to do an automated global replace?
...and add a checkstyle rule?
regards, toby
Re: The
javadoc antipattern
Posted by Julian Reschke <ju...@gmx.de>.
On 2014-06-16 18:29, Jukka Zitting wrote:
> Hi,
>
> [resurrecting an old thread, since it seems we still have some
> affected javadocs in Oak]
>
> On Wed, Apr 3, 2013 at 10:46 AM, Jukka Zitting <ju...@gmail.com> wrote:
>> A trivially minor, but long-standing annoyance of mine seems to be
>> creeping over from Jackrabbit to Oak:
>>
>> For some reason people are using "<p/>" as a paragraph break in
>> Javadoc comments. That's wrong on many levels. Javadoc comments are in
>> HTML, not XHTML, so the self-closing "<p/>" is strictly speaking
>> invalid. And even if they were in XHTML, "<p/>" would indicate a
>> separate, empty paragraph instead starting a new paragraph. I have no
>> idea where this convention comes from.
>>
>> So, if it's not too much to ask, use "<p>" instead of "<p/>" when
>> starting a new paragraph in javadoc. It'll make my inner perfectionist
>> feel better when browsing source code.
>
> Avoiding this anti-pattern will also prevent problems with Java 8,
> where the javadoc tool will by default refuse to accept such comments.
> See https://bugs.openjdk.java.net/browse/JDK-8020619.
Maybe we should try to do an automated global replace?
Best regards, Julian
Re: The
javadoc antipattern
Posted by Jukka Zitting <ju...@gmail.com>.
Hi,
[resurrecting an old thread, since it seems we still have some
affected javadocs in Oak]
On Wed, Apr 3, 2013 at 10:46 AM, Jukka Zitting <ju...@gmail.com> wrote:
> A trivially minor, but long-standing annoyance of mine seems to be
> creeping over from Jackrabbit to Oak:
>
> For some reason people are using "<p/>" as a paragraph break in
> Javadoc comments. That's wrong on many levels. Javadoc comments are in
> HTML, not XHTML, so the self-closing "<p/>" is strictly speaking
> invalid. And even if they were in XHTML, "<p/>" would indicate a
> separate, empty paragraph instead starting a new paragraph. I have no
> idea where this convention comes from.
>
> So, if it's not too much to ask, use "<p>" instead of "<p/>" when
> starting a new paragraph in javadoc. It'll make my inner perfectionist
> feel better when browsing source code.
Avoiding this anti-pattern will also prevent problems with Java 8,
where the javadoc tool will by default refuse to accept such comments.
See https://bugs.openjdk.java.net/browse/JDK-8020619.
BR,
Jukka Zitting