Use Triple-Slash Doc-Comment Style in Code Generated by slice2cpp
#3190
Conversation
There was a problem hiding this comment.
Generated code that should be ignored.
| %x C_COMMENT | ||
| %x C_DOC_COMMENT |
There was a problem hiding this comment.
At any moment the Slice scanner is in a specific state (called a "Start Condition").
This list contains all the possible states that it can be within.
Previously, we only had a single C_COMMENT state, and whenever the scanner was in this state, it would add any text it saw to the current doc-comment. This was bad.
So, now we have 2 states. C_DOC_COMMENT is triggered when the scanner sees /** and C_COMMENT is triggered when the scanner sees /*. The scanner will try to match rules in order so it will always try to match /** first.
And, the scanner will only add things to doc comments while it is in the C_DOC_COMMENT state.
| /* Matches the start of a C style doc-comment, and switches the scanner to the C_DOC_COMMENT state. */ | ||
| <*>"/**"/[^/*] { | ||
| yy_push_state(C_DOC_COMMENT); | ||
| } | ||
|
|
There was a problem hiding this comment.
This says "Enter the C_DOC_COMMENT start condition if you see a literal /** that is not followed by either a / or a * character.
The first case protects against /**/ (an empty C-style comment, not a doc comment), and the second protects against people who like to have banners like:
/*************************
Stuff
*************************/
A Slice doc comment must have exactly 2 stars. No more and no less.
| <C_COMMENT,C_DOC_COMMENT>"*" | | ||
| <C_COMMENT,C_DOC_COMMENT>[^\n*]+ { |
There was a problem hiding this comment.
In Flex syntax, anything in angle brackets means: "only match this rule if you are in one of these start conditions".
| if (YY_START == C_DOC_COMMENT) | ||
| { | ||
| currentUnit->setDocComment(comment.substr(0, yyleng - 2)); | ||
| } |
There was a problem hiding this comment.
We only set the text as a doc comment if we're in the C_DOC_COMMENT start condition,
even though this rule can be used in either the C_DOC_COMMENT or C_COMMENT start conditions.
|
There is yet another bug in some of our doc comment links, and this time it's not obvious why these are only becoming a problem now that we've switched to triple slashes. I'm going to close this PR for now, fix the other bugs that it's revealed, then afterwards I'll re-open it. |
This PR implements part of #1853 (switch to using
///comments for C++).Now,
slice2cppwill always generate///style comments instead of/** */comments.Additionally this PR also cleans up the comments in
slice2cppitself.For a demo of how this change affects the generated code, see: InsertCreativityHere@69ffaa6.
I checked in the generated code (from
./slice/Ice) before and after this PR, so I could double-check the difference.EDIT:
Implementing this actually revealed a pretty egregious bug in the Slice scanner.
It was treating all comments of the form
/* */as doc comments, when doc comments should require/**two stars on the opening slash.So, this whole time, we've been generating doc-comments for all C-style comments.
I only noticed it in this PR because the
Ice/operationstest has comments like/* \A\ */(of course).And now that we're using triple-slash comments, it is illegal to use the
\line-continuation character at the end...Needless to say, this PR also fixes this bug with the Slice scanner.