On 3/21/18 2:18 PM, Martin Buchholz wrote:
On Wed, Mar 21, 2018 at 1:59 PM, Jonathan Gibbons
<jonathan.gibb...@oracle.com <mailto:jonathan.gibb...@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
