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