ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jon Skeet" <jon.sk...@peramon.com>
Subject RE: [PATCH] /src/main/org/apache/tools/ant/IntrospectionHelper.java (More JavaDocs)
Date Wed, 20 Feb 2002 08:07:55 GMT
> On Tue, 19 Feb 2002, Jon Skeet <jon.skeet@peramon.com> 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.
> 
> We are using entities in javadocs in several other classes as well, I
> think Erik has replaced all occurences of unescaped <, > and & some
> months ago.
> 
> Bottom line, please don't use >. 8-)

Fair enough.

> > Possibly just (String-Class) or (String to Class)?
> 
> I prefer String to Class.

Right. I'll go for that. It's probably easiest from my point of view if yesterday's patch
is applied, then I'll work out another patch which fixes this for IntrospectionHelper and
all the other classes I've done. (I think there are probably only one or two cases, but I'd
rather do them in one go.)

I'll also submit a prospective code patch as mentioned in the notes, to reduce the length
of createAttributeSetter - if I keep that entirely separate, it can be viewed on its own merits
and chucked away if people don't like it :)

> > If it breaks things for 1.1 and/or 1.2 though, I'm happy to go back
> > and fix this up.
> 
> I think the javadocs should work for all people who compile Ant, which
> means they should work in 1.1, but then again, I'm sure I've added
> {@link a b} constructs in several places myself.
> 
> No religious issue, but 1.1 compatibility would be nice.

Yikes - I'd forgotten that @link didn't go back to 1.1. Hmm. There are 33 @link occurrences
in Ant non-optional stuff. They're just so handy :) Looking at the JavaDoc reference page,
it seems that @throws only came in with 1.2 as well - before then it was @exception. There
are 72 occurrences of @throws in the non-optional source (and 38 of @exception). I personally
prefer @throws as it reads better (and I wish @return was @returns, but that's another matter)
but I can fix these up as we go as well if necessary.

I'll ponder this one a bit further - any more guidance very welcome.

In the meantime, does anyone else know specifically when 

/** JavaDoc */
// Non JavaDoc
public void someMethod()
{
}

became fixed? I can't find it in the "bugs fixed" sections of the JavaDoc documentation.

Jon

--
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