[prev in list] [next in list] [prev in thread] [next in thread] 

List:       openjdk-net-dev
Subject:    Re: RFR [13] 8153508: ContentHandler API contains link to private contentPathProp
From:       Daniel Fuchs <daniel.fuchs () oracle ! com>
Date:       2019-03-19 12:54:36
Message-ID: f59bb3c1-80a9-35f3-1a7a-80f79eb3bc8e () oracle ! com
[Download RAW message or body]

Hi Chris,

Looks good to me.

@value: this is an interesting tag to know!

Powerful, useful, maybe dangerous too?
In this case the value in question is held in a *private*
static final field.
So {@link } was clearly wrong. But because the field
is private some future maintainer might well be tempted
to change its value without realizing that by doing so
he's (or she's) also changing the spec...

That said this a property name so unlikely to ever
change - and @value does avoid the risk of misspelling
the property name.

best regards,

-- daniel

On 19/03/2019 10:40, Chris Hegarty wrote:
> This review request is to resolve a documentation regression in Java 9,
> resulting from part of the changes for 8132478, where {@value
> java.net.URLConnection#contentPathProp} was inadvertently replaced with
> {@link java.net.URLConnection#contentPathProp}. The former will inline
> with the constant field value, where the latter will link to the
> ( private ) field.
> 
> The fix is to just revert the incorrect change.
> 
> --- a/src/java.base/share/classes/java/net/ContentHandler.java
> +++ b/src/java.base/share/classes/java/net/ContentHandler.java
> @@ -47,7 +47,7 @@
>    * If no content handler could be {@linkplain URLConnection#getContent() found},
>    * URLConnection will look for a content handler in a user-definable set of places.
>    * Users can define a vertical-bar delimited set of class prefixes
> - * to search through by defining the <i>{@link java.net.URLConnection#contentPathProp}</i>
> + * to search through by defining the <i>{@value java.net.URLConnection#contentPathProp}</i>
>    * property. The class name must be of the form:
>    * <blockquote>
>    *     <i>{package-prefix}.{major}.{minor}</i>
> 
> -Chris.
> 

[prev in list] [next in list] [prev in thread] [next in thread]