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="1741860377493-0.06458804786377892">{@code</code> <em>text</em> <code class="prettyprint" data-shared-secret="1741860377493-0.06458804786377892">}</code></li>
</ul>