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

[specification] inline tag brace balancing is not documented

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 15
    • Component/s: tools
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      source
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      There is no associated change in any behavior. This is just about providing a more complete specification.
    • Interface Kind:
      File or wire format
    • Scope:
      JDK

      Description

      Summary

      Provide details about the use of braces { and } within inline tags.

      Problem

      Although restricted use of braces is permitted within inline tags, the restrictions have not been documented, and should be.

      Solution

      Include additional text about braces in the Doc Comment specification.

      Specification

      The following text is inserted after the existing description for inline tags.

      --- a/closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md    Thu Jan 16 10:31:26 2020 -0800
      +++ b/closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md    Thu Jan 16 12:45:56 2020 -0800
      @@ -477,6 +477,16 @@
       Inline tags are enclosed within braces (`{ }`) and may generally appear
       wherever descriptive text and HTML is permitted.
      
      +Some inline tags may contain free-form text. When such text explicitly contains
      +braces, the braces must be "balanced", implying an equal number of appropriately
      +nested left brace and right brace characters, so that the closing brace of the
      +inline tag can be determined. No other lexical analysis of the text is
      +performed; in particular, there is no special consideration of characters like
      +`'`, `"`, and `\`.
      +
      +When the text content is HTML, it may be possible to use entities `{`
      +and `}` to represent unbalanced braces.
      +
       #### `{@code}`
      
      <ul>
      <li><code class="prettyprint" data-shared-secret="1582705200622-0.6598647359602005">{@code</code> <em>text</em> <code class="prettyprint" data-shared-secret="1582705200622-0.6598647359602005">}</code></li>
      </ul>

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                jjg Jonathan Gibbons
                Reporter:
                jrose John Rose
                Reviewed By:
                Hannes Wallnoefer, John Rose, Pavel Rappo
              • Votes:
                0 Vote for this issue
                Watchers:
                1 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: