[Mondrian] Javadoc clampdown

Julian Hyde julianhyde at speakeasy.net
Fri Feb 23 18:23:02 EST 2007


Developers,

I cleaned up all javadoc errors and warnings about a year ago, but since
then the number of javadoc errors and warnings has been building up. It's no
surprise why - it's easy to break javadoc links, and we have no had a
process for detecting new errors.

Until now, that is. I've added a check to the nightly regression process
which runs javadoc, substracts the errors which exist today (see attached),
and prints out what's left. If one of your changes introduces a javadoc
errors, you can expect an email from me.

Things to watch out for:

*	Empty parameter tags (e.g. "@param foo"). I'd prefer that all
parameters were documented, but if you've got nothing to say, don't say
anything.
*	Empty return tags (e.g. "@return"). As above.
*	Parameter tags which reference invalid parameters.
*	Javadoc on an inner class cannot reference a member or method of the
enclosing class without explicitly qualifying it with the class name. For
example, in the following {@link #value} should be {@link Foo#value}.

*	class Foo {
  int value;

  /** Wrapper for {@link #value}. */
  class Bar {
    int getValue() { return value; }
  }
}

*	As before, we require that all classes, and all public and protected
methods have javadoc. Overriding methods don't generally need javadoc,
unless their purpose is radically different than their base method. Method
comments should be in the present active mood: that is, the first word,
should generally end in 's'. See
<http://mondrian.pentaho.org/documentation/developers_guide.php> Developer's
Guide.

I recommend that you run 'ant javadoc' before checking in, to make sure
there are no javadoc errors or warnings in files you have touched.
 
Unfortunately if you touch an existing file, line numbers will change, and
existing javadoc errors will no longer be masked out. You'll just have to
fix those too.
 
Julian
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.pentaho.org/pipermail/mondrian/attachments/20070223/8a76c130/attachment.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/gif
Size: 145 bytes
Desc: not available
Url : http://lists.pentaho.org/pipermail/mondrian/attachments/20070223/8a76c130/attachment.gif 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: ant-javadoc-expected.log
Type: application/octet-stream
Size: 12547 bytes
Desc: not available
Url : http://lists.pentaho.org/pipermail/mondrian/attachments/20070223/8a76c130/attachment.obj 


More information about the Mondrian mailing list