[
https://issues.apache.org/jira/browse/AVRO-3294?focusedWorklogId=706702&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-706702
]
ASF GitHub Bot logged work on AVRO-3294:
----------------------------------------
Author: ASF GitHub Bot
Created on: 11/Jan/22 09:07
Start Date: 11/Jan/22 09:07
Worklog Time Spent: 10m
Work Description: 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 comment is necessary.
It 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]
Issue Time Tracking
-------------------
Worklog Id: (was: 706702)
Time Spent: 0.5h (was: 20m)
> IDL parsing allows doc comments in strange places
> -------------------------------------------------
>
> Key: AVRO-3294
> URL: https://issues.apache.org/jira/browse/AVRO-3294
> Project: Apache Avro
> Issue Type: Improvement
> Components: java, tools
> Reporter: Oscar Westra van Holthe - Kind
> Priority: Minor
> Labels: pull-request-available
> Fix For: 1.11.1
>
> Time Spent: 0.5h
> Remaining Estimate: 0h
>
> As demonstrated by the current test case
> {{TestIdl#testDocCommentsAndWarnings}} (and the files {{comments.avdl}} &
> {{comments.avpr}}), doc comments are not handled according to spec.
> Goal: use doc comments that are placed according to spec, and generate
> warnings for all misplaced doc comments.
--
This message was sent by Atlassian Jira
(v8.20.1#820001)
