On 01.10.2009 16:44:13 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?
>
> Yes.
>
> > > 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
>
> But I'm sure that the majority of developers is migrating to {...@code} or
> generally speaking away from HTML. One advantage except from not
> relaying on HTML is, that inside code you can use any character such as
> "<", "&" and ">" which isn't allowed in HTML or XML.
I'm not disputing any of that. It's just that my FOP development
environment is entirely running with Java 1.4. I'm always compiling with
Java 1.4 to minimize mistakes. Using Java 1.5 can simply complicate
things.
> > 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.
I've already fixed the obvious mistakes.
> Oh I see :-) So there are currently 105 usages of {...@code} in the trunk.
> What to do? Can't we allow {...@code} if we generate Javadoc with Java 1.5?
I guess it's no big deal. If people want clean javadocs they need to run
Javadoc 1.5. But IMO it's a bit premature to require {...@code} in our
conventions.
Jeremias Maerki
