#512 False alarm for first sentence of Javadoc in Japanese.

release_5.0
closed
Oliver Burn
5
2012-10-10
2008-05-03
MISHIMA Masahiro
No

False alarm will be railsed in case the first sentence of Javadoc ends with Idiographic Full Stop (\u3002).
This character is valid as well as period in Javadoc. It is usually used instead of period in Japanese.

Discussion

  • Logged In: YES
    user_id=662018
    Originator: NO

    According to the document "How to Write Doc Comments for the Javadoc Tool" under the section "Description":

    "... sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tag ..."

    http://java.sun.com/j2se/javadoc/writingdoccomments/#descriptions

    Will Javadoc use the character "Full Stop" as a period, and take the text before "Full Stop" and put that text into the Javadoc "Overview" page?

    If it doesn't, then I'd say the current behavior of the check is correct.

     
  • Logged In: YES
    user_id=395101
    Originator: YES

    Thanks for your response.
    Yes, I mean the text before "Full Stop" will be shown in the Javadoc "Overview" page actually.

    I don't know any reference materials which clearly defines this behavior of Javadoc.
    Looking into the source code of Javadoc itself, I found the following comment for the interface method com.sun.javadoc.Doc#firstSentenceTags().
    It suggests a sentence may end with other characters than period under some locale other than English, isn't it?

    File: com/sun/javadoc/Doc.java

    /**
     * Return the first sentence of the comment as an array of tags.
     * Includes inline tags
     * (i.e. {&#64link <i>reference</i>} tags)  but not
     * block tags.
     * Each section of plain text is represented as a {@link Tag}
     * of {@linkplain Tag#kind() kind} "Text".
     * Inline tags are represented as a {@link SeeTag} of kind "@see"
     * and name "@link".
     * <p>
     * If the locale is English language, the first sentence is
     * determined by the rules described in the Java Language
     * Specification (first version): &quot;This sentence ends
     * at the first period that is followed by a blank, tab, or
     * line terminator or at the first tagline.&quot;, in
     * addition a line will be terminated by block
     * HTML tags: &lt;p&gt;  &lt;/p&gt;  &lt;h1&gt;
     * &lt;h2&gt;  &lt;h3&gt; &lt;h4&gt;  &lt;h5&gt;  &lt;h6&gt;
     * &lt;hr&gt;  &lt;pre&gt;  or &lt;/pre&gt;.
     * If the locale is not English, the sentence end will be
     * determined by
     * {@link java.text.BreakIterator#getSentenceInstance(Locale)
     * java.text.BreakIterator.getSentenceInstance(Locale)}.
    
     * @return an array of {@link Tag}s representing the
     * first sentence of the comment
     */
    Tag[] firstSentenceTags();
    
     
  • haccy
    haccy
    2008-06-16

    Logged In: YES
    user_id=1192441
    Originator: NO

    I've created a patch(#1993103) that makes the format of end of sentence configurable.

     
  • Oliver Burn
    Oliver Burn
    2008-06-17

    Logged In: YES
    user_id=218824
    Originator: NO

    I have applied the patched referred to below that fixes the problem. In SVN revision 2403.