[jira] [Comment Edited] (REEF-333) Remove javadoc "first sentence period" checkstyle

["Markus Weimer (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/REEF-333?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14550618#comment-14550618 ] 

Markus Weimer edited comment on REEF-333 at 5/19/15 3:31 PM:
-------------------------------------------------------------

I think we should fix the code and keep the check in place. IDEs use the period to determine the end of the one-sentence summary shown in mouse-over help and in the ctrl-space popup.

Also, that sentence is used for index tables and such generated by javadoc, as described [here|http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#format]. This can be seen in action for instance in our documentation of the [driver package|http://reef.incubator.apache.org/apidocs/0.10.0-incubating/org/apache/reef/driver/package-summary.html] where {{FlexiblePreemptionEvent}} doesn't have a summary sentence at the beginning.



was (Author: markus.weimer):
I think we should fix the code and keep the check in place. IDEs use the period to determine the end of the one-sentence summary shown in mouse-over help and in the ctrl-space popup.

Also, that sentence is used for index tables and such generated by javadoc, as described [here|http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#format]. This can be seen in action for instance in our documentation of the [driver package|http://reef.incubator.apache.org/apidocs/0.10.0-incubating/index.html] where {{FlexiblePreemptionEvent}} doesn't have a summary sentence at the beginning.


> Remove javadoc "first sentence period" checkstyle
> -------------------------------------------------
>
>                 Key: REEF-333
>                 URL: https://issues.apache.org/jira/browse/REEF-333
>             Project: REEF
>          Issue Type: Sub-task
>          Components: All
>            Reporter: Brian Cho
>             Fix For: 0.12
>
>
> We get many of the following errors:
> javadoc	JavadocStyle	First sentence should end with a period.
> For example, reef-common has 158 errors.
> I skimmed our generated Javadoc, http://reef.incubator.apache.org/apidocs/0.10.0-incubating/index.html and I don't feel it's a major problem for documentation to miss the period. Thus, I propose to just remove the rule.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)