RFR: 7160725 - Strange or obsolete @see tags in some exception java.lang javadoc (original) (raw)

David Holmes david.holmes at oracle.com
Thu Apr 19 20:49:17 UTC 2012

Hi Jim,

On 20/04/2012 12:41 AM, Jim Gish wrote:

Hi David,

As I discussed with Alan, I don't think the conventions for @see in general are very clear. One could argue that there are a number of approaches that could be taken, among them: an exhaustive list, a representative list, or one simple example.

Or no example at all.

I just don't think this changes the level of "strangeness" as originally reported - and it would be interesting to know what the reporter thinks of the suggested change.

But this isn't worth extensive debate so if Alan and co are happy with this I'm not objecting.

Cheers, David

A complete enumeration in many cases (such as IAE, and NFE) is ridiculously large (something like 2700 for IAE if I recall correctly). Listing them all doesn't make sense, of course. So, in this particular case I was opting for a representative sample of uses - choosing the ones below for being common or typical from a "nearby" package - as being exmplars.

Of course, the principal point of this whole fix, was simply to give me a trivial change to run through to help learn the openjdk process, so unless the philosophy, policy, or convention is considered to be paramount, I'd prefer to "take a reasonable shot" at this, as I have done, and move on. Cheers, Jim ----- Original Message ----- From: david.holmes at oracle.com To: jim.gish at oracle.com Cc: core-libs-dev at openjdk.java.net Sent: Wednesday, April 18, 2012 8:12:43 PM GMT -05:00 US/Canada Eastern Subject: Re: RFR: 7160725 - Strange or obsolete @see tags in some exception java.lang javadoc Hi Jim, I guess I don't see the point here. There must be literally dozens of APIs that throw IllegalArgumentException, and a significant number that can throw NumberFormatError. What is so special about these selections? I'd argue for removing the old @see tags. David On 19/04/2012 5:47 AM, Jim Gish wrote: I've updated the copyrights to just have first and current year.

Jim On 04/18/2012 03:33 PM, Jim Gish wrote: Description:

Another trivial javadoc update - fixed existing @see ref and added a few more representative of the exception usage Patch: diff -r 00f5665ee0ea src/share/classes/java/lang/IllegalArgumentException.java --- a/src/share/classes/java/lang/IllegalArgumentException.java Tue Apr 17 09:30:29 2012 -0400 +++ b/src/share/classes/java/lang/IllegalArgumentException.java Wed Apr 18 15:28:26 2012 -0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1994, 2003, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1994, 2003, 2012 Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -30,7 +30,10 @@ * inappropriate argument. * * @author unascribed + * @see java.lang.Enum#valueOf(Class, String) * @see java.lang.Thread#setPriority(int) + * @see java.lang.Runtime#exec(String) + * @see java.lang.System#getProperty(String) * @since JDK1.0 */ public diff -r 00f5665ee0ea src/share/classes/java/lang/NumberFormatException.java --- a/src/share/classes/java/lang/NumberFormatException.java Tue Apr 17 09:30:29 2012 -0400 +++ b/src/share/classes/java/lang/NumberFormatException.java Wed Apr 18 15:28:26 2012 -0400 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1994, 2001, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1994, 2001, 2012 Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -31,7 +31,8 @@ * have the appropriate format. * * @author unascribed - * @see java.lang.Integer#toString() + * @see java.lang.Float#Float(String) + * @see java.lang.Integer#parseInt(String) * @since JDK1.0 */ public Thanks, Jim Gish

More information about the core-libs-dev mailing list