JavaDoc 中带注释的代码示例

Posted 2023-03-05

【中文标题】JavaDoc 中带注释的代码示例

【英文标题】：Code example with annotation in JavaDoc

【发布时间】：2011-02-07 19:54:06

【问题描述】：

当我有一个带有注释的代码示例时，我的 JavaDoc 不起作用。

有什么建议吗？

/**
 * <pre>
 * public class Demo 
 *    @DemoAnnotation
 *    public void demoMethod() 
 *    
 * 
 * </pre>
 */ 
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface DemoAnnotation 

【参考方案1】：

更通用的解决方案：@literal @

@literal 标签表示文字文本。包含的文本被解释为不包含 html 标记或嵌套的 javadoc 标记。例如，文档注释文本：@literal a<B>c 在生成的 HTML 页面中显示不变：a<B>c——即<B> 不会被解释为粗体。

需要 Java 5+

【讨论】：

在实际尝试之前对其进行了投票，但后来我注意到一个问题：使用@literal @ 在@ 之前添加了一个难看的空间（至少在NetBeans 中查看时）。 @ 没有（例如，它在 JUnit javadoc 中使用）。哦，并且它在 @code 内部不起作用（@ 起作用）。

@SergeyTachenov 无法使用命令行 javadoc 重现您的空间问题。 @code 行为是设计使然；有关如何在 javadoc 中嵌入复杂代码 sn-ps 的良好提示，请参阅此答案：***.com/a/13512524/159570

我还在

是的，但我认为您不会找到任何模板语言（Javadoc 或其他），它允许您内联任意文本而无需转义分隔符。有关正确的转义指南，请参阅我之前评论中的链接。

【参考方案2】：

您必须在 JavaDoc 中将 @ 替换为 @。

【参考方案3】：

像这样使用 ：

/**
 * <pre><code>
 *    public class Demo 
 *      @DemoAnnotation
 *      public void demoMethod() 
 *      
 *    
 * </code></pre>
 */ 

产生一个段落，而 单独也可以内联使用。

【参考方案4】：

你也可以使用@code 来转义注解，但是你必须像这样单独做每一个：

/**
 * <pre>
 * public class Demo 
 *   @code @DemoAnnotation 
 *   @code @AnotherAnnotation 
 *    public void demoMethod() 
 *    
 * 
 * </pre>
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface DemoAnnotation 

会这样渲染：

public class Demo 
    @DemoAnnotation
    @AnotherAnnotation
    public void demoMethod() 
    

注意：将两个注解（或整个代码示例）简单地包装在一个 @code 块中是行不通的。

【参考方案5】：

您必须使用@Documented 注释在javadoc 中添加注释。检查 API 上的实现

【讨论】：

这是不正确的：请阅读docs.oracle.com/javase/7/docs/api/java/lang/annotation/…