Please review a a new feature to allow `@link`, `@linkplain` and `@see` tags to
link to user-defined URL fragments in the generated documentation (including in
auxiliary `doc-files` documentation).
The changes in module `jdk.compiler` are mostly cleanup changes retained from
earlier versions of the patch. The current proposed version uses a very simple
change in `ReferenceParser` to avoid parsing the member name section of the
reference when a non-member fragment is encountered.
The implementation almost exactly follows the plan described in the JBS issue,
except that it supports both ways to mark a user defined fragment:
- a fragment name containing a `-` character
- a fragment starting with double `##`
The reason for supporting both ways is that the first option practically
imposes itself ('-' not being a valid character for member names and
auto-generated header ids making use of this), while the second is necessary to
support the existing `id` attributes in JDK and other sources which should be
usable with this feature without needing to be changed.
Links to auxiliary documentation files follow the same rules. They are
recognized by looking for `/` characters in the fragment name. This means that
ordinary `id` attribute values must not contain `/`, while auxiliary file paths
must contain a `/` character. Both restrictions should be easy to sustain.
One thing that is difficult for this feature is to provide a good link label if
no label is supplied in the tag. In contrast to program element names a
fragment name does usually not make a good human readable name. The solution is
to use the fragment name as default label text. I expect that the feature will
usually be used with a user provided label.
The CSR for this feature is still unfinished, I hope to get it ready for review
within the next few days.
-------------
Commit messages:
- Remove trailing whitespace
- Only support double hash as fragment/path indicator
- JDK-8200337: Generalize see and link tags for user-defined anchors
Changes: https://git.openjdk.org/jdk/pull/10395/files
Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=10395&range=00
Issue: https://bugs.openjdk.org/browse/JDK-8200337
Stats: 388 lines in 10 files changed: 333 ins; 16 del; 39 mod
Patch: https://git.openjdk.org/jdk/pull/10395.diff
Fetch: git fetch https://git.openjdk.org/jdk pull/10395/head:pull/10395
PR: https://git.openjdk.org/jdk/pull/10395
