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

Jim Gish jim.gish at oracle.com
Thu Apr 19 14:41:40 UTC 2012

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.

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