<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD><TITLE id=ridTitle>Blank</TITLE>
<META http-equiv=Content-Type content="text/html; charset=us-ascii">
<STYLE><!-- body { font-family: Arial, Helvetica; font-size: 10pt; color: #000000; margin-top: 25px; margin-left: 25px; } P.msoNormal, LI.msoNormal { font-family: Helvetica, "Times New Roman"; font-size: 10pt; margin-top: 0px; margin-left: 0px; color: "#ffffcc"; } --></STYLE>
<META content="MSHTML 6.00.6000.16414" name=GENERATOR></HEAD>
<BODY id=ridBody background=cid:883160223@23022007-25E9>
<P><SPAN class=883160223-23022007><FONT face=Verdana
color=#000080>Developers,</FONT></SPAN></P>
<P><SPAN class=883160223-23022007><FONT face=Verdana color=#000080>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.</FONT></SPAN></P>
<P><SPAN class=883160223-23022007><FONT face=Verdana color=#000080>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.</FONT></SPAN></P>
<P><SPAN class=883160223-23022007><FONT face=Verdana color=#000080>Things to
watch out for:</FONT></SPAN></P>
<UL>
<LI><SPAN class=883160223-23022007><FONT face=Verdana color=#000080>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.</FONT></SPAN></LI>
<LI><SPAN class=883160223-23022007><FONT face=Verdana color=#000080>Empty
return tags (e.g. "@return"). As above.</FONT></SPAN></LI>
<LI><SPAN class=883160223-23022007><FONT face=Verdana color=#000080>Parameter
tags which reference invalid parameters.</FONT></SPAN></LI>
<LI><SPAN class=883160223-23022007><FONT face=Verdana color=#000080>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}.</FONT></SPAN></LI>
<UL>
<LI><SPAN class=883160223-23022007><FONT face=Verdana color=#000080>class
Foo {<BR> int value;<BR><BR> /** Wrapper for {@link #value}.
*/<BR> class Bar {<BR> int getValue() { return
value; }<BR> }<BR>}</FONT></SPAN></LI></UL>
<LI><SPAN class=883160223-23022007><FONT face=Verdana color=#000080>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 <A class=contentSection_leftMenuQ id=contentSection_leftMenuQ
href="http://mondrian.pentaho.org/documentation/developers_guide.php"><SPAN
style="PADDING-LEFT: 15px">Developer's Guide</SPAN></A>.</FONT></SPAN></LI></UL>
<DIV><SPAN class=883160223-23022007><FONT face=Verdana color=#000080>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.</FONT></SPAN></DIV>
<DIV><SPAN class=883160223-23022007><FONT face=Verdana
color=#000080></FONT></SPAN> </DIV>
<DIV><SPAN class=883160223-23022007><FONT face=Verdana
color=#000080>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.</FONT></SPAN></DIV>
<DIV><SPAN class=883160223-23022007><FONT face=Verdana
color=#000080></FONT></SPAN> </DIV>
<DIV><SPAN class=883160223-23022007><FONT face=Verdana
color=#000080>Julian</FONT></SPAN></DIV></BODY></HTML>