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

[specification] inline tag brace balancing is not documented

    XMLWordPrintable

Details

    Description

      I have never seen the doc comment spec until the other day, so I was interested when Stuart gave the link. I noticed a missing bit, that I’ve always been curious about: Exactly how does a `{@code}` tag find its closing brace? There’s no hint about it, although there are some spotty hints that at least some inline tags can nest inside other tags. I think the doc should say more about this. I noticed that brace counting is included in the parsing of the `{@code}`. No other characters are significant, so braces inside double quotes count, even if they have a different meaning in Java code.

      Apparently all inline tags do simple brace balancing, regardless of the head of the tag. No other chars are significant. (I peeked at the code, and that’s the impression I got.)

      So, here's a documentation bug to track this mystery and its revelation.

      FTR here's a link to a relevant specification. It's good, but I don't think it helps me understand how nesting works.
      https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDJGIJB

      Attachments

        Issue Links

          Activity

            People

              jjg Jonathan Gibbons
              jrose John Rose
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: