如何在Znai的Java Callout Comment中渲染代码段并添加Code Reference？

一、让Java注释内联代码渲染为<code>等宽格式 #

1. 用Znai原生标记替代反引号/{@code} #

直接在Java类的Javadoc里使用Znai支持的[[...]]语法包裹需要渲染的代码段，比如：

/**
 * 本类由[[AnnotationProcessor]]生成，标记有[[@Generated]]注解
 */
public class DemoGeneratedClass {
    // 类实现代码
}

通过:include-java引入该类后，Znai会自动将[[@Generated]]和[[AnnotationProcessor]]解析为<code>包裹的等宽文本，符合预期格式。

2. 开启Java注释处理配置 #

检查项目根目录的znai.yaml，确保开启Java注释解析：

java:
  commentsProcessing: true

这是Znai正确解析注释内标记的必要前提。

二、为代码段添加Code Reference #

1. 引用本地代码位置 #

如果要让内联代码跳转到项目内的具体代码位置：

• 引入Java文件时指定锚点，比如锚定到@Generated注解的定义处：

  :include-java: src/main/java/com/example/Generated.java {anchor="GeneratedAnnotation"}
  

• 在Java注释中使用带引用参数的标记：

  /**
   * 自动生成的类标记有[[@Generated, ref=GeneratedAnnotation]]注解
   */
  

  渲染后点击@Generated即可跳转到指定锚点的代码位置。

2. 自定义引用说明 #

如果需要为代码段添加自定义描述（比如注解的作用说明）：

• 先在文档中定义引用：

  :define-reference: generated-annotation-ref
  :title: @Generated 注解
  :description: JDK提供的用于标记自动生成代码的注解，避免被代码检查工具修改
  :type: java
  

• 再在Java注释中关联该引用：

  /**
   * 类由[[AnnotationProcessor]]生成，标记了[[@Generated, ref=generated-annotation-ref]]
   */
  

  点击@Generated时会显示自定义的引用说明。

内容的提问来源于stack exchange，提问作者TheSilverNimbus