#614 Add "Single Property Comment" option to JavadocMethod

Future
closed
nobody
incomplete (2)
1
2014-08-23
2013-08-07
Ryan Baker
No

Creating Javadoc for Properties is valuable, but if done by any existing rules would result in a great deal of duplication. AllowMissingPropertyJavadoc allows to complete ignore all properties, but a more ideal solution is one in which you only need one comment to cover the getter and setter, and that the getter does not require a @return tag nor the setter an @param tag.

At the base a property is a singular item, and sensibly only requires explanation once. Comments like "Sets myProperty" are useless cruft and best avoided, and copying the whole explanation of what a property is into four places is almost as bad.

While a full implementation would probably involve cross-checking between getter/setter's for existence, a reasonable compromise would be to simply never require a comment for any setter's, and disable @return requirements for the setter.

The setter requirement could be implemented in isMissingJavadocAllowed, something like this:

protected boolean isMissingJavadocAllowed(final DetailAST aAST) {
  return mAllowMissingJavadoc || isOverrideMethod(aAST) || 
    || (mOneJavadocPerProperty && isSetterMethod(aAST))
    || (mAllowMissingPropertyJavadoc && (isGetterMethod(aAST) || isSetterMethod(aAST)));
}

Changing the return tag would require passing aAST into checkReturnTag:

private void checkReturnTag(List<JavadocTag> aTags, DetailAST aAST, int aLineNo, boolean aReportExpectedTags) {
  // Loop over tags finding return tags. After the first one, report an
  // error.
  boolean found = false;
  final ListIterator<JavadocTag> it = aTags.listIterator();
  while (it.hasNext()) {
    final JavadocTag jt = it.next();
    if (jt.isReturnTag()) {
      if (found) {
        log(jt.getLineNo(), jt.getColumnNo(), "javadoc.duplicateTag", JavadocTagInfo.RETURN.getText());
            }
      found = true;
      it.remove();
    }
  }

  // Handle there being no @return tags :- unless
  // the user has chosen to suppress these problems
  if (!found && !mAllowMissingReturnTag && !(mOneJavadocPerProperty && isGetterMethod(aAST)) && aReportExpectedTags) {
    log(aLineNo, "javadoc.return.expected");
  }
}

Discussion

  • Ryan Baker
    Ryan Baker
    2013-08-07

    Should have said at end of third paragraph:

    " and disable @return requirements for the getter."

     
  • Roman Ivanov
    Roman Ivanov
    2013-10-03

    • labels: --> incomplete
     
  • Ivan Sopov
    Ivan Sopov
    2014-02-05

    • status: open --> closed