opwvhk commented on a change in pull request #1453:
URL: https://github.com/apache/avro/pull/1453#discussion_r781195567
##########
File path:
lang/java/compiler/src/main/java/org/apache/avro/compiler/idl/DocCommentHelper.java
##########
@@ -74,6 +74,14 @@ static void setDoc(Token token) {
DOC.set(newDocComment);
}
+ /**
+ * Clear any documentation (and generate a warning if there was).
+ *
+ * This method should NOT be used after an optional component in a grammar
+ * (i.e., after a @code{[…]} or @code{…*} construct), because the optional
+ * grammar part may have already caused parsing a doc comment special token
+ * placed after the code block.
+ */
Review comment:
Although the code is not public, this comments is necessary.
It also describes the reason the method is called so many times in `idl.jj`,
and why the implementation of doc comments as special tokens (as opposed to
regular tokens) is a hack.
The only reason to keep it (for now) is because changing that aspect of the
grammar may break existing `.avdl` files. We can still change this after people
have had time to fix the warnings generated by this change.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
