ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Bill Burton" <bi...@progress.com>
Subject Re: [PATCH] /src/main/org/apache/tools/ant/IntrospectionHelper.java (More JavaDocs)
Date Tue, 19 Feb 2002 21:27:47 GMT
Hi Jon,

Jon Skeet wrote:
> 
> > Saw a couple of minor issues with this patch.
> > 1. In many places is this: (String->Class).
> >    It would be better as: (String-&gt;Class).
> 
> I pondered this myself. Obviously from a purist point of view, you're right - but then
the source code ends up being harder to read. (These comments tend to be for fields which
are private, and thus most likely to be seen in the context of viewing the source code, which
makes it more of a problem.) I tried to think up some alternatives, but couldn't come up with
anything as good. Possibly just (String-Class) or (String to Class)?

Good points.

> > 2. In at least a couple of places you've added // comments after the
> > javadoc comment but before a method, i.e. IntrospectionHelper and
> > createAttributeSetter.  Unless something's changed in a
> > recent version of
> > javadoc, the // comments will prevent javadoc from
> > associating the javadoc
> > comment with the method, etc. below it.  Have you checked to make sure
> > javadoc is being generated for these methods?
> 
> It's certainly working with the 1.4 JavaDoc. (I'm using that to get rid of breakiterator
warnings as I go.) I'm pretty sure it was working when I used 1.3.1 as well, although I can't
be sure. If it breaks things for 1.1 and/or 1.2 though, I'm happy to go back and fix this
up. Any caveats about putting those comments just *before* the JavaDoc comments?

I don't ever recall hearing there is a requirement to build the javadoc
with the 1.1 version just because the code should build and run in a 1.1
JVM.

I'm fairly certain the problem I saw with comments being dropped was with
some version of 1.2 javadoc before 1.2.2.  The committers will have to
clarify whether javadoc support needs to work with 1.2.2 or if 1.3.1 is
okay.  Javadoc 1.4 is okay for fixing problems as you've pointed out but
since 1.3 is the mainstream version, it really needs to at least format
correctly with that version.

Along this line, I've been using the Adriana prerelease of the IDEA IDE
(http://www.intellij.com/eap/).  When you open a class file, it highlights
javadoc syntax errors as well as Java ones.  All you have to do is scan
down the right frame border looking for red or yellow bars.  Clicking on a
bar jumps to the place where it found the error.  Renaming a parameter
using the refactoring rename also renames the associated javadoc parameter
as well.

-Bill

--
To unsubscribe, e-mail:   <mailto:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message