Java 12下OSGi版本注解生成Javadoc异常错误排查

这不是Java 12的回归问题，而是Javadoc工具在Java 12版本中对package级注解的处理逻辑发生了变化，再结合OSGi注解的特殊使用场景才导致的报错。

问题根源 #

在Java 11及更早版本中，Javadoc工具不会将package-info.java里package声明前的注解识别为Javadoc标签；但Java 12的Javadoc工具默认会扫描这些位置的注解，并尝试将其解析为Javadoc标签。由于@org.osgi.annotation.versioning.Version是OSGi用于版本控制的专用注解，并非标准Javadoc标签，因此工具会抛出unknown tag: Version的错误。

解决方案 #

你可以通过以下几种方式解决这个问题：

• 方式一：将OSGi的@Version注解注册为自定义Javadoc标签
  如果希望在生成的Javadoc中保留版本信息，可以通过Maven Javadoc插件配置，告诉工具将@Version视为合法的自定义标签。在项目的pom.xml中添加如下配置：

  <build>
      <plugins>
          <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-javadoc-plugin</artifactId>
              <!-- 请使用支持Java 12的插件版本，比如3.1.1及以上 -->
              <version>3.2.0</version>
              <configuration>
                  <additionalparam>-tag Version:a:"Version:"</additionalparam>
              </configuration>
          </plugin>
      </plugins>
  </build>
  

  配置后，Javadoc工具会将@Version注解的内容渲染为Javadoc中的"Version:"条目。

• 方式二：让Javadoc工具忽略OSGi的@Version注解
  如果不需要在Javadoc中展示这个版本信息，可以配置工具直接跳过该注解的解析：

  <build>
      <plugins>
          <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-javadoc-plugin</artifactId>
              <version>3.2.0</version>
              <configuration>
                  <additionalparam>-excludeAnnotations org.osgi.annotation.versioning.Version</additionalparam>
              </configuration>
          </plugin>
      </plugins>
  </build>
  

• 方式三：确保使用兼容Java 12的Maven Javadoc插件版本
  旧版本的maven-javadoc-plugin可能对Java 12的Javadoc工具支持不佳，建议升级插件到3.1.1或更高版本，这能避免不少兼容性问题。

额外验证 #

你也可以直接通过Javadoc命令行工具测试配置是否有效，比如执行：

javadoc -tag Version:a:"Version:" -d target/javadoc src/main/java/org/apache/jackrabbit/oak/commons/package-info.java

如果能正常生成Javadoc，就说明配置是有效的。

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