Need sponsor to fix Javadoc warnings

David Holmes david.holmes at oracle.com
Thu Apr 9 00:16:45 UTC 2020 

Hi Pavel,

On 8/04/2020 11:23 pm, Pavel Rappo wrote:
> Hey David,
> 
> Where exactly? In the files affected by this changeset? If so, then we will
> introduce inconsistency. Otherwise it's a huge change. From what I can see there
> are some 250 occurrences of `@exception` in src/java.base/share/classes/com/sun/{crypto, security}
> and some 7,300 in src.

Okay as I said I didn't examine in detail to see the size of the change 
- and its obviously too big.

> Personally, out of all tag renovations, changing `@exception` to `@throws`
> probably gives the least bang for the buck. If nothing else, it gives you 3
> extra characters on the same line to fill with something more useful.

There was an effort to do this conversion a while back, at least while 
touching affected files. It's not a big deal to me.

Cheers,
David

> I would be more inclined to change `<code>...</code>` to `{@code ...}`, but
> given how error-prone that can be, I still wouldn't do it in this changeset.
> 
> -Pavel
> 
>> On 8 Apr 2020, at 13:56, David Holmes <david.holmes at oracle.com> wrote:
>>
>> Hi Pavel,
>>
>> Not a review ...
>>
>> On 8/04/2020 9:50 pm, Pavel Rappo wrote:
>>> Vipin, here you go:
>>>      https://bugs.openjdk.java.net/browse/JDK-8242366
>>>      http://cr.openjdk.java.net/~prappo/8242366/webrev.00/
>>> I took the liberty of additionally fixing a couple of parameters' names,
>>> a typo, and `@exception` tags for checked exceptions that were neither thrown
>>> nor imported.
>>
>> While you are in there is it worth changing @exception to @throws? (I didn't look to see how big that change would be.)
>>
>> Cheers,
>> David
>>
>>> The bulk of the change is in Security. Some changes are in Networking. The
>>> appropriate mailing lists are in CC for this email. We should wait for their
>>> feedback.
>>> Changes in core area look good to me and I'd be surprised if there are any
>>> problems with the remaining portion of the changeset.
>>> -Pavel
>>>> On 7 Apr 2020, at 19:50, Vipin Sharma <vipinsharma85 at gmail.com> wrote:
>>>>
>>>> Hi Pavel,
>>>>
>>>>> On Apr 7, 2020, at 11:11 PM, Pavel Rappo <pavel.rappo at oracle.com> wrote:
>>>>>
>>>>> I assume you have signed the OCA [1]. If not and you want to continue, please do it. If you've already done so, which is probably the case [2], please attach your patch as text to this thread with the next email. Do not use zip or the like. I will take it from there and sponsor that for you.
>>>> Yes I have signed OCA.
>>>>>
>>>>> -Pavel
>>>>>
>>>>> [1] https://www.oracle.com/technetwork/community/oca-486395.html
>>>>> [2] changeset:   58344:65f30e209890
>>>>> user:        clanger
>>>>> date:        Wed Mar 11 13:50:13 2020 +0100
>>>>> files:       test/jdk/java/lang/Boolean/GetBoolean.java test/jdk/java/lang/Boolean/MakeBooleanComparable.java test/jdk/java/lang/Boolean/ParseBoolean.java
>>>>> description:
>>>>> 8240524: Remove explicit type argument in test jdk/java/lang/Boolean/MakeBooleanComparable.java
>>>>> Reviewed-by: clanger, vtewari
>>>>> Contributed-by: vipinsharma85 at gmail.com
>>>>>
>>>> Yes this is my first contribution.
>>>>
>>>> Patch text:
>>>>
>>>> --- old/src/java.base/share/classes/com/sun/crypto/provider/AESCipher.java	2020-04-06 00:19:10.546117441 +0530
>>>> +++ new/src/java.base/share/classes/com/sun/crypto/provider/AESCipher.java	2020-04-06 00:19:10.130115855 +0530
>>>> @@ -1,5 +1,5 @@
>>>> /*
>>>> - * Copyright (c) 2002, 2017, Oracle and/or its affiliates. All rights reserved.
>>>> + * Copyright (c) 2002, 2020, 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
>>>> @@ -202,7 +202,7 @@
>>>>      /**
>>>>       * Sets the padding mechanism of this cipher.
>>>>       *
>>>> -     * @param padding the padding mechanism
>>>> +     * @param paddingScheme the padding mechanism
>>>>       *
>>>>       * @exception NoSuchPaddingException if the requested padding mechanism
>>>>       * does not exist
>>>> --- old/src/java.base/share/classes/com/sun/crypto/provider/AESWrapCipher.java	2020-04-06 00:19:11.526121179 +0530
>>>> +++ new/src/java.base/share/classes/com/sun/crypto/provider/AESWrapCipher.java	2020-04-06 00:19:11.118119622 +0530
>>>> @@ -1,5 +1,5 @@
>>>> /*
>>>> - * Copyright (c) 2004, 2017, Oracle and/or its affiliates. All rights reserved.
>>>> + * Copyright (c) 2004, 2020, 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
>>>> @@ -313,10 +313,10 @@
>>>>       * current Cipher.engineInit(...) implementation,
>>>>       * IllegalStateException will always be thrown upon invocation.
>>>>       *
>>>> -     * @param in the input buffer
>>>> -     * @param inOffset the offset in <code>in</code> where the input
>>>> +     * @param input the input buffer
>>>> +     * @param inputOffset the offset in <code>in</code> where the input
>>>>       * starts
>>>> -     * @param inLen the input length.
>>>> +     * @param inputLen the input length.
>>>>       *
>>>>       * @return n/a.
>>>>       *
>>>> --- old/src/java.base/share/classes/com/sun/crypto/provider/BlowfishCrypt.java	2020-04-06 00:19:12.462124749 +0530
>>>> +++ new/src/java.base/share/classes/com/sun/crypto/provider/BlowfishCrypt.java	2020-04-06 00:19:12.054123193 +0530
>>>> @@ -1,5 +1,5 @@
>>>> /*
>>>> - * Copyright (c) 1998, 2007, Oracle and/or its affiliates. All rights reserved.
>>>> + * Copyright (c) 1998, 2020, 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
>>>> @@ -130,7 +130,6 @@
>>>>       *
>>>>       * @param plain the buffer with the input data to be encrypted
>>>>       * @param plainOffset the offset in <code>plain</code>
>>>> -     * @param plainLen the length of the input data
>>>>       * @param cipher the buffer for the result
>>>>       * @param cipherOffset the offset in <code>cipher</code>
>>>>       */
>>>> @@ -154,7 +153,6 @@
>>>>       *
>>>>       * @param cipher the buffer with the input data to be decrypted
>>>>       * @param cipherOffset the offset in <code>cipherOffset</code>
>>>> -     * @param cipherLen the length of the input data
>>>>       * @param plain the buffer for the result
>>>>       * @param plainOffset the offset in <code>plain</code>
>>>>       */
>>>> --- old/src/java.base/share/classes/com/sun/crypto/provider/DESCrypt.java	2020-04-06 00:19:13.414128382 +0530
>>>> +++ new/src/java.base/share/classes/com/sun/crypto/provider/DESCrypt.java	2020-04-06 00:19:12.998126795 +0530
>>>> @@ -1,5 +1,5 @@
>>>> /*
>>>> - * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
>>>> + * Copyright (c) 1997, 2020, 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
>>>> @@ -552,7 +552,6 @@
>>>>       *
>>>>       * @param plain the buffer with the input data to be encrypted
>>>>       * @param plainOffset the offset in <code>plain</code>
>>>> -     * @param plainLen the length of the input data
>>>>       * @param cipher the buffer for the result
>>>>       * @param cipherOffset the offset in <code>cipher</code>
>>>>       *
>>>> @@ -579,7 +578,6 @@
>>>>       *
>>>>       * @param cipher the buffer with the input data to be decrypted
>>>>       * @param cipherOffset the offset in <code>cipherOffset</code>
>>>> -     * @param cipherLen the length of the input data
>>>>       * @param plain the buffer for the result
>>>>       * @param plainOffset the offset in <code>plain</code>
>>>>       *
>>>> --- old/src/java.base/share/classes/com/sun/crypto/provider/GaloisCounterMode.java	2020-04-06 00:19:14.374132046 +0530
>>>> +++ new/src/java.base/share/classes/com/sun/crypto/provider/GaloisCounterMode.java	2020-04-06 00:19:13.958130458 +0530
>>>> @@ -1,5 +1,5 @@
>>>> /*
>>>> - * Copyright (c) 2013, 2019, Oracle and/or its affiliates. All rights reserved.
>>>> + * Copyright (c) 2013, 2020, 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
>>>> @@ -262,8 +262,6 @@
>>>>       * @param algorithm the algorithm name
>>>>       * @param key the key
>>>>       * @param iv the iv
>>>> -     * @param tagLenBytes the length of tag in bytes
>>>> -     *
>>>>       * @exception InvalidKeyException if the given key is inappropriate for
>>>>       * initializing this cipher
>>>>       */
>>>> --- old/src/java.base/share/classes/com/sun/crypto/provider/PBEKeyFactory.java	2020-04-06 00:19:15.314135635 +0530
>>>> +++ new/src/java.base/share/classes/com/sun/crypto/provider/PBEKeyFactory.java	2020-04-06 00:19:14.898134047 +0530
>>>> @@ -1,5 +1,5 @@
>>>> /*
>>>> - * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
>>>> + * Copyright (c) 1997, 2020, 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
>>>> @@ -225,7 +225,7 @@
>>>>       *
>>>>       * @param key the key
>>>>       *
>>>> -     * @param keySpec the requested format in which the key material shall be
>>>> +     * @param keySpecCl the requested format in which the key material shall be
>>>>       * returned
>>>>       *
>>>>       * @return the underlying key specification (key material) in the
>>>> --- old/src/java.base/share/classes/com/sun/crypto/provider/PBES1Core.java	2020-04-06 00:19:16.270139285 +0530
>>>> +++ new/src/java.base/share/classes/com/sun/crypto/provider/PBES1Core.java	2020-04-06 00:19:15.846137666 +0530
>>>> @@ -92,7 +92,7 @@
>>>>       * Sets the padding mechanism of this cipher. This algorithm only uses
>>>>       * PKCS #5 padding.
>>>>       *
>>>> -     * @param padding the padding mechanism
>>>> +     * @param paddingScheme the padding mechanism
>>>>       *
>>>>       * @exception NoSuchPaddingException if the requested padding mechanism
>>>>       * is invalid
>>>> --- old/src/java.base/share/classes/com/sun/crypto/provider/PBKDF2Core.java	2020-04-06 00:19:17.206142859 +0530
>>>> +++ new/src/java.base/share/classes/com/sun/crypto/provider/PBKDF2Core.java	2020-04-06 00:19:16.798141302 +0530
>>>> @@ -1,5 +1,5 @@
>>>> /*
>>>> - * Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved.
>>>> + * Copyright (c) 2005, 2020, 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
>>>> @@ -75,7 +75,7 @@
>>>>       *
>>>>       * @param key the key
>>>>       *
>>>> -     * @param keySpec the requested format in which the key material shall be
>>>> +     * @param keySpecCl the requested format in which the key material shall be
>>>>       * returned
>>>>       *
>>>>       * @return the underlying key specification (key material) in the
>>>> --- old/src/java.base/share/classes/com/sun/crypto/provider/Padding.java	2020-04-06 00:19:18.138146421 +0530
>>>> +++ new/src/java.base/share/classes/com/sun/crypto/provider/Padding.java	2020-04-06 00:19:17.722144831 +0530
>>>> @@ -1,5 +1,5 @@
>>>> /*
>>>> - * Copyright (c) 1997, 2007, Oracle and/or its affiliates. All rights reserved.
>>>> + * Copyright (c) 1997, 2020, 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
>>>> @@ -49,7 +49,7 @@
>>>>       * interface.
>>>>       *
>>>>       * @param in the input buffer with the data to pad
>>>> -     * @param the offset in <code>in</code> where the padding bytes
>>>> +     * @param off the offset in <code>in</code> where the padding bytes
>>>>       *  are appended
>>>>       * @param len the number of padding bytes to add
>>>>       *
>>>> --- old/src/java.base/share/classes/java/lang/ProcessBuilder.java	2020-04-06 00:19:19.086150043 +0530
>>>> +++ new/src/java.base/share/classes/java/lang/ProcessBuilder.java	2020-04-06 00:19:18.670148453 +0530
>>>> @@ -1077,7 +1077,7 @@
>>>>       * Start a new Process using an explicit array of redirects.
>>>>       * See {@link #start} for details of starting each Process.
>>>>       *
>>>> -     * @param redirect array of redirects for stdin, stdout, stderr
>>>> +     * @param redirects array of redirects for stdin, stdout, stderr
>>>>       * @return the new Process
>>>>       * @throws IOException if an I/O error occurs
>>>>       */
>>>> --- old/src/java.base/share/classes/java/util/GregorianCalendar.java	2020-04-06 00:19:20.050153727 +0530
>>>> +++ new/src/java.base/share/classes/java/util/GregorianCalendar.java	2020-04-06 00:19:19.634152137 +0530
>>>> @@ -731,7 +731,7 @@
>>>>       * Constructs an empty GregorianCalendar.
>>>>       *
>>>>       * @param zone    the given time zone
>>>> -     * @param aLocale the given locale
>>>> +     * @param locale the given locale
>>>>       * @param flag    the flag requesting an empty instance
>>>>       */
>>>>      GregorianCalendar(TimeZone zone, Locale locale, boolean flag) {
>>>> --- old/src/java.base/share/classes/sun/net/util/IPAddressUtil.java	2020-04-06 00:19:21.042157520 +0530
>>>> +++ new/src/java.base/share/classes/sun/net/util/IPAddressUtil.java	2020-04-06 00:19:20.630155944 +0530
>>>> @@ -1,5 +1,5 @@
>>>> /*
>>>> - * Copyright (c) 2004, 2015, Oracle and/or its affiliates. All rights reserved.
>>>> + * Copyright (c) 2004, 2020, 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
>>>> @@ -316,7 +316,7 @@
>>>>       * If the address already has a scope-id or if the address is not local, ipv6
>>>>       * or link local, then the original address is returned.
>>>>       *
>>>> -     * @param addr
>>>> +     * @param address
>>>>       * @exception SocketException if the given ipv6 link local address is found
>>>>       *            on more than one local interface
>>>>       * @return
>>>> --- old/src/java.base/share/classes/sun/net/www/protocol/https/HttpsClient.java	2020-04-06 00:19:22.266162200 +0530
>>>> +++ new/src/java.base/share/classes/sun/net/www/protocol/https/HttpsClient.java	2020-04-06 00:19:21.854160624 +0530
>>>> @@ -1,5 +1,5 @@
>>>> /*
>>>> - * Copyright (c) 2001, 2018, Oracle and/or its affiliates. All rights reserved.
>>>> + * Copyright (c) 2001, 2020, 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
>>>> @@ -208,7 +208,7 @@
>>>>       * Use New to get new HttpsClient. This constructor is meant to be
>>>>       * used only by New method. New properly checks for URL spoofing.
>>>>       *
>>>> -     * @param URL https URL with which a connection must be established
>>>> +     * @param url https URL with which a connection must be established
>>>>       */
>>>>      private HttpsClient(SSLSocketFactory sf, URL url)
>>>>      throws IOException
>>>> --- old/src/java.base/share/classes/sun/security/jca/ProviderConfig.java	2020-04-06 00:19:23.502166928 +0530
>>>> +++ new/src/java.base/share/classes/sun/security/jca/ProviderConfig.java	2020-04-06 00:19:23.082165322 +0530
>>>> @@ -321,7 +321,7 @@
>>>>          /**
>>>>           * Loads the provider with the specified class name.
>>>>           *
>>>> -         * @param name the name of the provider
>>>> +         * @param pn the name of the provider
>>>>           * @return the Provider, or null if it cannot be found or loaded
>>>>           * @throws ProviderException all other exceptions are ignored
>>>>           */
>>>> --- old/src/java.base/share/classes/sun/security/provider/certpath/BasicChecker.java	2020-04-06 00:19:24.446170540 +0530
>>>> +++ new/src/java.base/share/classes/sun/security/provider/certpath/BasicChecker.java	2020-04-06 00:19:24.034168963 +0530
>>>> @@ -1,5 +1,5 @@
>>>> /*
>>>> - * Copyright (c) 2000, 2012, Oracle and/or its affiliates. All rights reserved.
>>>> + * Copyright (c) 2000, 2020, 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
>>>> @@ -72,7 +72,7 @@
>>>>       * Constructor that initializes the input parameters.
>>>>       *
>>>>       * @param anchor the anchor selected to validate the target certificate
>>>> -     * @param testDate the time for which the validity of the certificate
>>>> +     * @param date the time for which the validity of the certificate
>>>>       *        should be determined
>>>>       * @param sigProvider the name of the signature provider
>>>>       * @param sigOnly true if only signature checking is to be done;
>>>> --- old/src/java.base/share/classes/sun/security/provider/certpath/Builder.java	2020-04-06 00:19:25.394174168 +0530
>>>> +++ new/src/java.base/share/classes/sun/security/provider/certpath/Builder.java	2020-04-06 00:19:24.982172591 +0530
>>>> @@ -1,5 +1,5 @@
>>>> /*
>>>> - * Copyright (c) 2000, 2018, Oracle and/or its affiliates. All rights reserved.
>>>> + * Copyright (c) 2000, 2020, 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
>>>> @@ -69,7 +69,7 @@
>>>>      /**
>>>>       * Initialize the builder with the input parameters.
>>>>       *
>>>> -     * @param params the parameter set used to build a certification path
>>>> +     * @param buildParams the parameter set used to build a certification path
>>>>       */
>>>>      Builder(BuilderParams buildParams) {
>>>>          this.buildParams = buildParams;
>>>> --- old/src/java.base/share/classes/sun/text/DictionaryBasedBreakIterator.java	2020-04-06 00:19:26.618178853 +0530
>>>> +++ new/src/java.base/share/classes/sun/text/DictionaryBasedBreakIterator.java	2020-04-06 00:19:26.210177291 +0530
>>>> @@ -1,5 +1,5 @@
>>>> /*
>>>> - * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved.
>>>> + * Copyright (c) 1999, 2020, 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
>>>> @@ -111,7 +111,7 @@
>>>>       * @param ruleFile       the name of the rule data file
>>>>       * @param ruleData       the rule data loaded from the rule data file
>>>>       * @param dictionaryFile the name of the dictionary file
>>>> -     * @param dictionartData the dictionary data loaded from the dictionary file
>>>> +     * @param dictionaryData the dictionary data loaded from the dictionary file
>>>>       * @throws MissingResourceException if rule data or dictionary initialization failed
>>>>       */
>>>>      public DictionaryBasedBreakIterator(String ruleFile, byte[] ruleData,
>>>>
>>>>
>>>>>> On 6 Apr 2020, at 17:07, Vipin Sharma <vipinsharma85 at gmail.com> wrote:
>>>>>>
>>>>>> Hi David,
>>>>>>
>>>>>> I forgot to mention this is my second patch here. I am new to this project, as per my understanding we need to contribute 3 patches to get user id and space on cr.openjdk.java.net, for now I need sponsor who can create bug id and upload this webrev on cr.openjdk.java.net
>>>>>> Please suggest if there is any way I can create my user id to upload this patch.
>>>>>>
>>>>>> This is ~300 line patch file.
>>>>>>
>>>>>> Regards,
>>>>>> Vipin
>>>>>>
>>>>>>> On Apr 6, 2020, at 3:25 AM, David Holmes <david.holmes at oracle.com> wrote:
>>>>>>>
>>>>>>> Hi Vipin,
>>>>>>>
>>>>>>> On 6/04/2020 6:42 am, Vipin Sharma wrote:
>>>>>>>> Hi,
>>>>>>>> I have fixed a few warnings where the method parameter name is different in
>>>>>>>> code and Javadoc, need a sponsor for this patch.
>>>>>>>> Webrev is available at
>>>>>>>> https://drive.google.com/open?id=1EXUXKqGxzSR7sW2LShy0sgvP4z-bPL0e
>>>>>>>
>>>>>>> webrevs needs to be hosted on OpenJDK systems - either cr.openjdk.java.net, or inline in an email to the list (not an attachment) if small enough.
>>>>>>>
>>>>>>> Thanks,
>>>>>>> David
>>>>>>>
>>>>>>>> Regards,
>>>>>>>> Vipin
>>>>>>
>>>>>
>>>> Thanks,
>>>> Vipin
>

More information about the security-dev mailing list