On Thu, 30 Mar 2023 17:24:11 GMT, Jonathan Gibbons <j...@openjdk.org> wrote:
> Please review a change to add `@spec` tags (and remove some equivalent `@see` > tags) to the main "core-libs" packages in `java.base` module. > > This is similar to, and a subset of, PR #11073. That PR was withdrawn, and > based on the ensuing discussion and suggestion, is now being handled with a > series of PRs for various separate parts of the system. Follow-up PRs will > be provided for the rest of `java.base`, for `java.desktop`, and for XML > APIs. The "LangTools" modules have already been updated. The "External > Specifications" page has been temporarily [disabled][] until this work is > complete. > > While the primary content of the change was automated, I've manually adjusted > the formatting, to break long lines. > > It is clear there is significant inconsistency in the ordering of block tags > in doc comment. We might want to (separately) consider normalizing the > order of the tags, perhaps according to the order defined for the tags in the > generated output, as given [here][] > > [here]: > https://github.com/openjdk/jdk/blob/83cf28f99639d80e62c4031c4c9752460de5f36c/make/Docs.gmk#L68 > [disabled]: > https://github.com/openjdk/jdk/blob/83cf28f99639d80e62c4031c4c9752460de5f36c/make/Docs.gmk#L115 > I skimmed through the changes and it looks quite good, much more workable > than PR 11073. > > Do you have a proposed ordering with other tags? I expected it would go with > @see but I see several where @SPEC is before @author, and @see after @author. > I know it doesn't really matter. The initial assumption was "after the @param/@return/@throws group". Overall, as I said in the description for this PR, the block tags are not very consistent about ordering. I was thinking we might want to recommend an overall ordering, but I'm worried it would be too intrusive a change to apply generally. In the description, I suggested an ordering based on the order in `Docs.gmk` which defines the order in which tags appear in the generated output. ------------- PR Comment: https://git.openjdk.org/jdk/pull/13248#issuecomment-1490920050
