On 01.10.2009 15:55:57 Alexander Kiel wrote:
> Hi Jeremias,
> 
> there is a JavadocStyleCheck. I have it includes in my
> checkstyle-5.0.xml for testing. I use the standard settings. It tests
> for empty JavaDoc and missing points in the first line.

Yes, but it can't check for that mandatory line between the body and the
parameters, right?

> I didn't found anything which checks for {...@code} instead of <tt> and
> <code>. Can we add the use of {...@code} instead of <tt> and <code> to the
> conventions page?

It took me some searching to find out where that {...@code} is even
specified. It seems to be a Javadoc 1.5 feature:
http://java.sun.com/javase/6/docs/technotes/tools/windows/javadoc.ht...@code
Please note that we're technically still on Java 1.4. A {...@code} results
in a warning and its content is swallowed with Javadoc 1.4.

Sun's styleguide still lists <code> for keywords and names:
http://java.sun.com/j2se/javadoc/writingdoccomments/#styleguide

While researching I found that I seem to have used @code accidentally in
some places but with the actual intention of using @link (see
IFDocumentHandler, for example). What a mess. :-( I'll fix that.

> 
> Best Regards
> Alex
> 
> 
> On Thu, 2009-10-01 at 15:37 +0200, Jeremias Maerki wrote:
> > On 01.10.2009 15:08:55 Vincent Hennebert wrote:
> > > Hi Alexander,
> > > 
> > > Alexander Kiel wrote:
> > > > Hi,
> > > > 
> > > > do we use <code>, <tt> or {...@code}? I found all three version. Is 
> > > > there a
> > > > Checkstyle for that?
> > > 
> > > Use {...@code}. HTML tags should be avoided as much as possible.
> > > 
> > > 
> > > > Do we introduce a newline between the Javadoc body and the @param,
> > > > @return or @throws clause?
> > > 
> > > Yes.
> > 
> > I'm sure Vincent wanted to write "Yes, that would be my preference.".
> > "We", the project as a whole, have no such rule.
> > 
> > Our code conventions are here:
> > http://xmlgraphics.apache.org/fop/dev/conventions.html
> > plus the Checkstyle configuration which has become a de-facto standard,
> > you could say. Everything beyond that is personal preference.
> > 
> > That said, I'm against over-regulating. Can you actually check that
> > blank line in Checkstyle? I don't think so. Going beyond what we already
> > have in terms of conventions doesn't make much sense as long as noone
> > fixes each and every Checkstyle violation in FOP.
> > 
> > > 
> > > > Again I see both:
> > > > 
> > > >     /**
> > > >      * create the /Font object
> > > >      *
> > > >      * @param fontname the internal name for the font
> > > >      * @param subtype the font's subtype
> > > >      * @param basefont the base font name
> > > >      * @param encoding the character encoding schema used by the font
> > > >      */
> > > > 
> > > >     /**
> > > >      * Sets the Encoding value of the font.
> > > >      * @param encoding the encoding
> > > >      */
> > > > 
> > > > 
> > > > Best Regards
> > > > Alex
> > > 
> > > Vincent
> > 
> > 
> > 
> > 
> > Jeremias Maerki
> > 
> > 




Jeremias Maerki

Reply via email to