On Thu, 10 Nov 2022 12:01:11 GMT, Alan Bateman <al...@openjdk.org> wrote:
> I'm trying to understand what "fix-ups" will be needed if the automated patch > is applied. In some cases, it looks the same spec will be linked from "See > also" and "External Specifications", e.g. > http://cr.openjdk.java.net/~jjg/8296546/api.00/java.base/java/net/StandardSocketOptions.html#TCP_NODELAY > so the `@see` ref can be dropped. > > In other cases we will have inline refs and the same URL in the `@spec`. This > may be okay for the short term but maybe there is a way to inline `@spec` to > avoid the duplication? > > There will probably be a bit of cleanup to reflow some lines, e.g. > StandardSocketOptions.java, as excessively long lines are problematic for > side-by-side diffs. The utility I mentioned has the (optional) ability to remove `@see` links when the text of the link exactly matches that used by the `@spec` tag. Unfortunately, the text is typically not exactly the same, and would require manual analysis to see if the `@see` tag can be removed. When inline references are used, the wording is very rarely the primary title of the spec: it is more likely to be a word or phrase that makes sense in the context of the enclosing sentence. _History: version 1 of this feature tried replacing inline links and `@see` tags with a bi-modal `@spec` tag. The results were "not good", especially in the generated external-specs page. Version 2 used a side file to provide the definitive title for each spec, but that was deemed to be too much of a maintenance issue. This is version 3, in which we've eliminated the side-file in favor of duplicating the title in each `@spec` tag._ ------------- PR: https://git.openjdk.org/jdk/pull/11073