Code Review 6706251: api/java_net/NetworkInterface/index.html#misc: getDisplayName() returned non null but empty String

[Andrew John Hughes]

On 19 March 2010 16:08, Michael McMahon <Michael.McMahon at sun.com> wrote:
> Looks good to me.
>
> - Michael.
>
> Christopher Hegarty - Sun Microsystems Ireland wrote:
>>
>> How about (thanks to Alan for the wording):
>>
>>      * A display name is a human readable String describing the network
>>      * device.
>>      *
>> -     * @return the display name of this network interface,
>> -     *         or null if no display name is available.
>> +     * @return a non-empty string representing the display name of this
>> network
>> +     *         interface, or null if no display name is available.
>>      */
>>     public String getDisplayName() {
>> -        return displayName;
>> +        /* strict TCK conformance */
>> +        return "".equals(displayName) ? null : displayName;
>>     }
>>      * A display name is a human readable String describing the network
>>      * device.
>>      *
>> -     * @return the display name of this network interface,
>> -     *         or null if no display name is available.
>> +     * @return a non-empty string representing the display name of this
>> network
>> +     *         interface, or null if no display name is available.
>>      */
>>     public String getDisplayName() {
>> -        return displayName;
>> +        /* strict TCK conformance */
>> +        return "".equals(displayName) ? null : displayName;
>>     }
>>
>> Updated Webrev:
>>  http://cr.openjdk.java.net/~chegar/6706251/webrev.00/webrev/
>>
>> -Chris.
>>
>> On 19/03/2010 15:33, Andrew John Hughes wrote:
>>>
>>> On 19 March 2010 15:12, Alan Bateman<Alan.Bateman at sun.com>  wrote:
>>>>
>>>> Christopher Hegarty - Sun Microsystems Ireland wrote:
>>>>>
>>>>> :
>>>>> I vaguely remember the history of this issue (Michael will know
>>>>> better),
>>>>>  but the expectation from the API is that while empty string is not
>>>>> disallowed if the display name cannot be retrieved then null should be
>>>>> returned.
>>>>>
>>>>> I think such a clarification is unnecessary in the API, it is such a
>>>>> corner case, and may be confusing.
>>>>
>>>> If the empty string is not allowed then changing the @return to make
>>>> this
>>>> clear would be good.
>>>>
>>>> -Alan.
>>>>
>>>
>>> The @return currently says 'the display name of this network
>>> interface, or null if no display name is available.'
>>>
>>> 'null if the display name is either null or the empty string' may be
>>> clearer.  It's these kind of corner cases that are a major pain for
>>> users of the API.
>
>

+1; seen that language on other Javadocs.
-- 
Andrew :-)

Free Java Software Engineer
Red Hat, Inc. (http://www.redhat.com)

Support Free Java!
Contribute to GNU Classpath and the OpenJDK
http://www.gnu.org/software/classpath
http://openjdk.java.net

PGP Key: 94EFD9D8 (http://subkeys.pgp.net)
Fingerprint: F8EF F1EA 401E 2E60 15FA  7927 142C 2591 94EF D9D8