[PATCH] 9053056: Anchor name conflict in ClassLoader JavaDoc
jonathan.gibbons at oracle.com
Wed Mar 21 21:26:27 UTC 2018
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 :-)
More information about the core-libs-dev