Re: RFR: 7160725 - Strange or obsolete @see tags in some exception java.lang javadoc
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@oracle.com To: jim.gish@oracle.com Cc: core-libs-dev@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
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@oracle.com To: jim.gish@oracle.com Cc: core-libs-dev@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
On 19/04/2012 21:49, David Holmes wrote:
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. Someone pointed out on the list [1] that there were a couple of references to types/methods that are outdated and should be updated or removed. I don't think it's worth doing an exhaustive update, just ensure that the obvious references are relevant/useful. I'm not aware of any guidelines or conventions as such.
-Alan [1] http://mail.openjdk.java.net/pipermail/core-libs-dev/2012-January/008913.htm...
participants (3)
-
Alan Bateman
-
David Holmes
-
Jim Gish