[11] [PATCH] 9053056: Anchor name conflict in ClassLoader JavaDoc

[Jonathan Gibbons]

On 3/21/18 2:18 PM, Martin Buchholz wrote:
>
>
> On Wed, Mar 21, 2018 at 1:59 PM, Jonathan Gibbons 
> <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> wrote:
>
>
>     I think that maybe we should establish a convention such that
>     user-defined anchors can never conflict with javadoc-generated
>     anchors. Using an embedded "-" (as in this proposal) in
>     user-defined anchors is a good start.
>
>
> It never occurred to me that use of "-" in an anchor can prevent 
> future conflicts with java identifiers.  This is another reason to use 
> multi-word anchors with "-" as separator, which I was already 
> personally leaning towards.
If you're (still) using javadoc with -html4, then the set of legal 
characters in an id is limited, and javadoc makes use of '-' to encode 
signatures, so you're still somewhat at risk for a clash. But, if you 
use -html5, the set of characters is much less limited ("no spaces") and 
javadoc does not resort to encoding with `-`. All of which says, "use 
'-' and HTML5".

>     A secondary proposal would be to have doclint check for potential
>     clashes. Even though we may use access filters to restrict the set
>     of elements included in any documentation, it should never be good
>     to facilitate clashes that may be caused by non-default options or
>     non-default tools.
>
>
> Javadoc runs with -private over all the sources needs a lower bar than 
> with the default, but certain classes of errors like broken links 
> should be made impossible by design of the release process.
I foresee an investigation and potential cleanup :-)

-- Jon