[
https://issues.apache.org/jira/browse/AVRO-3239?focusedWorklogId=685714&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-685714
]
ASF GitHub Bot logged work on AVRO-3239:
----------------------------------------
Author: ASF GitHub Bot
Created on: 24/Nov/21 08:27
Start Date: 24/Nov/21 08:27
Worklog Time Spent: 10m
Work Description: opwvhk commented on a change in pull request #1377:
URL: https://github.com/apache/avro/pull/1377#discussion_r755799501
##########
File path:
lang/java/compiler/src/main/javacc/org/apache/avro/compiler/idl/idl.jj
##########
@@ -95,12 +95,57 @@ public class Idl implements Closeable {
String namespace;
Map<String,Schema> names = new LinkedHashMap<String,Schema>();
- private static final ThreadLocal<String> DOC = new ThreadLocal<String>();
- static void setDoc(String doc) { DOC.set(doc.trim()); }
+ private static class DocComment {
+ private String text;
+ private int line;
+ private int column;
+ DocComment(Token token) {
+ // The token is everything after the initial '/**', including all
whitespace and the ending '*/'
+ int tokenLength = token.image.length();
+ this.text = token.image.substring(0, tokenLength-2)./*replaceAll("[
\\t]*(\\r|\\r\\n|\\n)[ \\t]*\\*?[ \\t]*", "$1").*/trim();
+ this.line = token.beginLine;
+ this.column = token.beginColumn - 3; // The preceding token was
"/**", and the current match includes everything since (also all whitespace).
+ }
+ }
+ // Using ThreadLocal fields because the generated IdlTokenManager has no
reference to the Idl instance but needs to give us the documentation comment.
+ private static final ThreadLocal<DocComment> DOC = new
ThreadLocal<DocComment>();
+ private static final ThreadLocal<List<String>> WARNINGS = new
ThreadLocal<List<String>>() {
+ @Override protected List<String> initialValue() {
+ return new ArrayList<String>();
+ }};
+ /**
+ * Return all warnings that were encountered while parsing, once. Subsequent
calls before parsing again will return an empty list.
+ */
+ public List<String> getWarningsAfterParsing() {
+ List<String> warnings = WARNINGS.get();
+ WARNINGS.remove();
+ return warnings;
+ }
+ static void setDoc(Token token) {
+ DocComment newDocComment = new DocComment(token);
+ DocComment oldDocComment = DOC.get();
+ if (oldDocComment != null) {
+ WARNINGS.get().add(String.format(
+ "Found documentation comment at line %d, column %d. Ignoring
previous one at line %d, column %d: \"%s\"\n" +
+ "A common cause is to use documentation comments ( /** ... */ )
instead of multiline comments ( /* ... */ ).",
+ newDocComment.line, newDocComment.column, oldDocComment.line,
oldDocComment.column, oldDocComment.text));
+ }
+ DOC.set(newDocComment);
+ }
+ static void clearDoc() {
+ DocComment oldDocComment = DOC.get();
+ if (oldDocComment != null) {
+ WARNINGS.get().add(String.format(
+ "Ignoring out-of-place documentation comment at line %d, column %d:
\"%s\"\n" +
+ "A common cause is to use documentation comments ( /** ... */ )
instead of multiline comments ( /* ... */ ).",
+ oldDocComment.line, oldDocComment.column, oldDocComment.text));
+ }
+ DOC.remove();
+ }
Review comment:
This method is not used yet, but in preparation of ignoring misplaced
documentation (for example halfway a `fixed` type declaration).
--
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: 685714)
Time Spent: 40m (was: 0.5h)
> IDL parsing silently ignores dangling documentation comments
> ------------------------------------------------------------
>
> Key: AVRO-3239
> URL: https://issues.apache.org/jira/browse/AVRO-3239
> Project: Apache Avro
> Issue Type: Improvement
> Components: java, spec, tools
> Affects Versions: 1.8.2, 1.9.2, 1.10.2
> Reporter: Oscar Westra van Holthe - Kind
> Priority: Minor
> Labels: pull-request-available
> Fix For: 1.11.1
>
> Attachments: comments.avdl, comments.avpr
>
> Time Spent: 40m
> Remaining Estimate: 0h
>
> When parsing IDL, only the last documentation comment for a declaration is
> used.
> Any previous documentation comments are silently ignored.
> Proposed fix: while keeping the exact same parsing results, emit warnings for
> each documentation comment that is ignored.
> Additional suggestion: mention that a common cause for such a warning is
> using a documentation comment instead of a multiline comment.
--
This message was sent by Atlassian Jira
(v8.20.1#820001)
