At the moment, the Syntax field in documentation examples is limited to a list of one-liners, and nothing else is allowed. Unfortunately, this includes formatting tags, such as versioning tags (e.g. <!-- if version [gte C++11] -->
and <!-- end version if -->
). Due to this, applying versioning to the Syntax field is more awkward than it needs to be.
Ideally:
- Syntax
- Syntax
<!-- if version [gte C++11] -->
- C++11-or-later Syntax
- C++11-or-later Syntax
<!-- end version if -->
Unfortunately, this isn't allowed, and gives the error message Syntax must be formatted as a list of one-liners
. Due to this, the best that can currently be done, to my knowledge, is something like this:
- Syntax
- Syntax
- // C++11 or later:
- C++11-or-later Syntax
- C++11-or-later Syntax
I feel that this is an abuse of the list formatting used for Syntax, but I honestly can't think of any other way to indicate that some syntax is version-specific. As such, I would like to request that versioning tags, and perhaps other, similar formatting tags, be allowed, as long as the actual examples still use the appropriate list formatting.
Also see:
- A related bug report.
- A related feature request, which doesn't visually demonstrate the issue.
}
brace, which will be about 2 lines lower than it should be. This is much less important at the moment, though.