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

Reply via email to