On Wed, Mar 21, 2018 at 1:59 PM, Jonathan Gibbons < 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. > 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.
