java - 在 Antlr 3 中生成自定义 JavaDoc

Question

我在 Antlr 3 中为我的公司实现了一种语法语言。目前，生成代码时没有任何注释。我想对注释进行编码，以便出现自定义注释。例如:

/**
* This class does something.
* @author name
*/
public class GrammarLanguageExample() {
}

语法语言的示例如下所示:

grammar Example;

options {
output=AST;
}

@header {
package com.example;
}

@rulecatch {
// ANTLR does not generate its normal rule try/catch
catch(RecognitionException e) {
    throw e;
}
}


insert      : 'INSERT INTO table' 'VALUES';
QUOTE       : '"';
SPECIALCHAR : '-'|'~'|;
STRING  : QUOTE('a'..'z'|'A'..'Z'|SPECIALCHAR|WS)+QUOTE;
WS: (' '|'\t'|'\f'|'\n'|'\r')+ { $channel = HIDDEN;}; // hide token from parser

上面的语法只是一个例子，并不是完整的语法。当代码由 AntlrWorks 3.4 生成时，当前会发生什么:

我得到两个 Java 文件:ExampleLexer 和 ExampleParser。

在ExampleLexer中，没有包信息。我希望它进入 com.example 包，而 ExampleParser 包含 com.example 包。每次语法更改时，我都必须输入 com.example 以便 Lexer 代码进行编译。如何更改语法中的代码以便添加包信息？

另外，我如何添加自定义 JavaDoc 注释？我想要这种格式:

package com.example;

Then import statements;

/**
* This class is used for Lexer.
* @author name
*/
public class ExampleLexer() {
}

package com.example;

Then import statements

/**
* This class is used for parsing.
* @author
*/
public class ExampleParser() {
}

我还想删除包信息之前自动生成的注释，它告诉我们语法何时生成。这怎么可能？

希望能帮到你。我在 Google 上进行了搜索，但找不到任何相关内容。

Answer 1

In the ExampleLexer, there is no package information. [...] How can I change the code in the grammar so that the package information is added?

对于组合语法文件(同时生成词法分析器和标记解析器的文件)，指定包名称需要指定两个 header 部分:一个用于词法分析器，一个用于解析器。正如您所发现的，@header 仅适用于解析器。以下是使用两个 header 部分的示例:

@parser::header {
    package com.example;
    //parser's imports go here.
}

@lexer::header { 
    package com.example;
    //lexer's imports go here.
}

Also, how would I add custom JavaDoc comments?

我认为组合语法只能为解析器类指定Javadoc注释，而不能为词法分析器指定。这是通过在声明语法之前添加文档注释来完成的:

/**
* This class is used for parsing.
* @author name
*/
grammar Example;

输出是您所期望的:

/**
* This class is used for parsing.
* @author name.
*/
@SuppressWarnings({"all", "warnings", "unchecked"})
public class ExampleParser extends Parser {
 //etc

我认为获得词法分析器类的 Javadoc 注释的唯一方法是专门为词法分析器创建一个语法文件并为其提供文档注释:

/**
* Lexer!
* @author name
*/
lexer grammar ExampleLexer;

输出为:

/**
* Lexer!
* @author name
*/
@SuppressWarnings({"all", "warnings", "unchecked"})
public class ExampleLexer extends Lexer {
     //etc

因此，您必须决定是需要一个仅在解析器上包含 Javadoc 的组合语法文件，还是需要两个语法文件以及您可以处理的所有 Javadoc。

I would also like to remove the auto generated comments before the package information, that tells when the grammar was generated. How is this possible?

ANTLR 不提供 command line option允许这样做，所以它不太可能自动完成。

如果您预计会有很多访问者浏览您生成的文件(听起来就像您所做的那样)，请考虑明确这些文件实际上是生成的，并且读者应该在其他地方查找完整的文档(并且不应进行更改)。您可以通过在文件顶部添加一个又大又难看的注释来轻松完成此操作，如下所示:

@parser::header {

    //!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
    //!!!                                                            !!!
    //!!! THIS CODE IS AUTOMATICALLY GENERATED! DO NOT MODIFY!       !!!
    //!!! Please refer to file Example.g for grammar documentation.  !!!
    //!!!                                                            !!!
    //!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

    package com.example;
}