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

[Jim Gish]

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
>