Apache NetBeans 中 Javadoc 内联标签格式化问题解析

问题背景

在 Apache NetBeans 22 版本中，开发者发现了一个关于 Javadoc 内联标签格式化的缺陷。具体表现为当使用 {@return foo} 这样的内联标签时，源代码格式化功能会错误地将其处理为块级标签，导致格式化后的代码结构被破坏。

问题现象

原始代码示例：

/**
 * {@return foo}
 */
String bar() {
    return null;
}

经过 NetBeans 格式化后变为：

/**
 *
 * {
 *
 * @return foo}
 */
String bar() {
    return null;
}

这种格式化结果明显不符合预期，不仅破坏了代码结构，还影响了文档的可读性。

技术分析

根本原因

1. 标签类型识别错误：NetBeans 的格式化引擎将所有 @return 标签都视为块级标签处理，而实际上自 Java 16 起，@return 既可以作为块级标签也可以作为内联标签使用。

2. 内联标签支持不足：格式化引擎中维护的内联标签白名单不完整，没有包含所有合法的内联标签类型，特别是较新版本 Java 引入的标签。

影响范围

这个问题不仅影响 @return 标签，还会影响任何未被明确列入内联标签白名单的合法内联标签。这可能导致开发者在编写符合最新 Java 规范的文档注释时遇到格式化问题。

解决方案

该问题已通过代码提交修复，主要改进包括：

1. 更新了内联标签识别逻辑，正确处理 @return 作为内联标签的情况
2. 完善了内联标签的白名单机制
3. 确保格式化引擎能够区分块级标签和内联标签的使用场景

最佳实践建议

1. 对于使用较新 Java 特性的项目，建议升级到修复后的 NetBeans 版本
2. 编写 Javadoc 时，注意区分内联标签和块级标签的使用场景
3. 定期检查格式化后的代码，确保文档注释的结构保持完整

总结

这个问题的修复不仅解决了 {@return} 标签的格式化问题，还提升了 NetBeans 对现代 Java 文档注释标准的支持度。作为开发者，了解工具对文档注释的处理方式有助于编写更规范、更易维护的代码文档。