Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8288875

Allow @systemProperty to appear in overview documentation

XMLWordPrintable

    • Icon: CSR CSR
    • Resolution: Approved
    • Icon: P3 P3
    • 19
    • tools
    • None
    • behavioral
    • minimal
    • Hide
      Currently, if `{@systemProperty}` appears in overview or doc-files, it will be processed as if those were allowed contexts.

      If this CSR is not integrated before JDK-8287379 [^1], while such `{@systemProperty}` will still be processed, it will also result in warning(s).

      -----
      [^1]: An unrelated issue for `{@inheritDoc}` that enables inline tag checks
      Show
      Currently, if `{@systemProperty}` appears in overview or doc-files, it will be processed as if those were allowed contexts. If this CSR is not integrated before JDK-8287379 [^1], while such `{@systemProperty}` will still be processed, it will also result in warning(s). ----- [^1]: An unrelated issue for `{@inheritDoc}` that enables inline tag checks
    • File or wire format

      Summary

      Allow @systemProperty to appear in overview and doc-files documentation.

      Problem

      Although {@systemProperty} is closely related to the predating {@index}, the contexts in which these tags can appear differ. Unlike {@index}, {@systemProperty} tags are not allowed to appear in overview documentation (specified by the "-overview" option of javadoc) or doc-files/**/*.html files. Not only is it surprising, but it is also awkward:

      • jdk.javadoc has active tests that ensure that {@systemProperty} can be used in overview and doc-files
      • 33 out of 34 networking properties in the JDK API are defined using {@systemProperty} in src/java.base/share/classes/java/net/doc-files/net-properties.html

      Note: The problem may have arisen because the tag was originally intended to be used to provide a single normative definition of the system property, at the smallest enclosing documented declaration, which would not have included "overview" documentation. However, that policy was eventually changed to permit the tag to be used for any significant or defining reference to the system property, thus effectively permitting its use in all places.

      Solution

      Specify that @systemProperty can also appear in the overview and doc-files documentation.

      Specification

      diff --git a/closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md b/closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md
index ce2e928fc5..7a2d959600 100644
--- a/closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md
+++ b/closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md
@@ -1040,7 +1040,7 @@ Table: Contexts in which tags may be used
 | [`@since`](#since)                    | ✓  | ✓ | ✓ | ✓ | ✓     | ✓ | ✓ |
 | [`
{@snippet}
`](#snippet)              | ✓  | ✓ | ✓ | ✓ | ✓     | ✓ | ✓ |
 | [`
{@summary}
`](#summary)              | ✓  | ✓ | ✓ | ✓ | ✓     | ✓ | ✓ |
-| [`
{@systemProperty}
`](#systemproperty)|          | ✓ | ✓ | ✓ | ✓     | ✓ | ✓ |
+| [`
{@systemProperty}
`](#systemproperty)| ✓  | ✓ | ✓ | ✓ | ✓     | ✓ | ✓ |
 | [`@throws`](#throws)                  |          |         |         |         | ✓     | ✓ |         |
 | [`@uses`](#uses)                      |          | ✓ |         |         |             |         |         |
 | [`
{@value}
`](#value)                  | ✓  | ✓ | ✓ | ✓ | ✓     | ✓ | ✓ |

            prappo Pavel Rappo
            prappo Pavel Rappo
            Jonathan Gibbons
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Created:
              Updated:
              Resolved: