[jira] [Work logged] (AVRO-3294) IDL parsing allows doc comments in strange places

["ASF GitHub Bot (Jira)" <ji...@apache.org>]

     [ 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: issues-unsubscribe@avro.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


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)