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

[David Holmes]

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