在Antlr 3中生成自定义JavaDoci

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包。每次语法发生变化时，我都必须输入Lexer代码的com.example进行编译。如何更改语法中的代码以便添加包信息？

另外，如何添加自定义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

在ExampleLexer中，没有包信息。 [...]如何更改语法中的代码，以便添加包信息？

用于组合的语法文件（一个同时产生词法分析器和令牌解析器），指定包名需要指定两个header部分：一个用于词法分析器和一个用于解析器。正如你发现的，@header只适用于解析器。下面是一个使用两个头部分的例子：

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

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

此外，我将如何添加自定义的JavaDoc注释？

我认为组合语法只能为解析器类而不是词法分析器指定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。

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

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; 
}