bigywater.tech
Java · 273

Javadoc 自定义标签:让 API 文档表达团队约定

想让 API 文档表达团队约定(负责团队、弃用原因、实现规范),就要自定义 Javadoc 标签。-tag 的位置字符有什么作用?Taglet 能做什么?标签没定义时 javadoc 怎么处理?这篇用真实的 javadoc 运行逐项验证。

6 条
默认 javadoc 对示例里没有定义的标签的 unknown tag 错误数
X
-tag 的位置字符:禁用标签(内容不输出、不报错)
2 处
Taglet 在示例里输出的位置数(类 1 个、方法 1 个)

没有定义的标签

实测 · 本机执行输出 
  默认 javadoc:返回码 1;诊断:
    <jtmp>/j133w/src/shop/Order.java:4: error: unknown tag: apiNote
    <jtmp>/j133w/src/shop/Order.java:5: error: unknown tag: owner
    <jtmp>/j133w/src/shop/Order.java:12: error: unknown tag: implSpec
    <jtmp>/j133w/src/shop/Order.java:13: error: unknown tag: owner
    <jtmp>/j133w/src/shop/Order.java:15: error: unknown tag: deprecated-reason
    <jtmp>/j133w/src/shop/Order.java:20: error: unknown tag: undefinedtag
    <jtmp>/j133w/src/shop/Order.java:7: warning: use of default constructor, which does not provide a comment
    6 errors
    1 warning
  生成的 Order.html 里能找到 @apiNote 的内容「创建后不可变」吗: False ;@owner 的内容「payments-team」: False ;@implSpec 的内容: False
  加 -Xdoclint:none:返回码 0;诊断条数 0

-tag 选项

实测 · 本机执行输出 
  -tag apiNote:a:… -tag implSpec:a:… -tag owner:a:… -tag deprecated-reason:m:… -tag undefinedtag:X:(X 表示禁用):返回码 0;诊断:
    <jtmp>/j133w/src/shop/Order.java:7: warning: use of default constructor, which does not provide a comment
    1 warning
  「API 说明」在 Order.html 里: nk">Object 订单。 API 说明: 创建后不可变。 负责团队: payments-team <section class="constructor-sum
  「实现规范」在 Order.html 里: /code> - 数量 Returns: 总价 Since: 1.2 实现规范: 默认实现是 qty * price。 负责团队: pricing-team 弃用原因: 改用 total(int, Money) check <div
  「负责团队」在 Order.html 里: lass="block">订单。 API 说明: 创建后不可变。 负责团队: payments-team <h
  「弃用原因」在 Order.html 里: 实现规范: 默认实现是 qty * price。 负责团队: pricing-team 弃用原因: 改用 total(int, Money) check public &nbsp;<span class=
  被 X 禁用的 @undefinedtag 的内容是否出现在页面里: False
  -tag owner:t:…(t 只允许出现在类型上):返回码 1;类上的 @owner 出现 = True ;方法上的 @owner 出现 = False ;诊断: ['<jtmp>/j133w/src/shop/Order.java:4: error: unknown tag: apiNote', '<jtmp>/j133w/src/shop/Order.java:12: error: unknown tag: implSpec', '<jtmp>/j133w/src/shop/Order.java:15: error: unknown tag: deprecated-reason']

Taglet

实测 · 本机执行输出 
  -taglet team.OwnerTaglet -tagletpath:返回码 0;诊断: ['<jtmp>/j133w/src/shop/Order.java:7: warning: use of default constructor, which does not provide a comment', '1 warning']
  自定义 Taglet 输出的内容: >Object 订单。 负责团队(自定义 Taglet) payments-team API 说明: 创建后不可变。 <section
  类级别与方法级别各出现的次数: 2 次(类 1 个、方法 1 个应该共 2 次)
  -taglet 指向不存在的类:返回码 1; ['error: Error - Exception java.lang.ClassNotFoundException thrown while trying to register Taglet team.NoSuchTaglet...', '<jtmp>/j133w/src/shop/Order.java:4: error: unknown tag: apiNote']

与 doclint 的关系

实测 · 本机执行输出 
  -Xdoclint:all(默认没有定义自定义标签):返回码 1;诊断:
    <jtmp>/j133w/src/shop/Order.java:4: error: unknown tag: apiNote
    <jtmp>/j133w/src/shop/Order.java:5: error: unknown tag: owner
    <jtmp>/j133w/src/shop/Order.java:12: error: unknown tag: implSpec
    <jtmp>/j133w/src/shop/Order.java:13: error: unknown tag: owner
    <jtmp>/j133w/src/shop/Order.java:15: error: unknown tag: deprecated-reason
    <jtmp>/j133w/src/shop/Order.java:20: error: unknown tag: undefinedtag
    <jtmp>/j133w/src/shop/Order.java:7: warning: use of default constructor, which does not provide a comment
    6 errors
    1 warning
  同样的 -tag 加 -Xdoclint:all:返回码 0;诊断条数 2; ['<jtmp>/j133w/src/shop/Order.java:7: warning: use of default constructor, which does not provide a comment', '1 warning']

分步演示

Javadoc 自定义标签
本步的对象

    本文用到的工具与边界

    • 本机 macOS 27 arm64 / OpenJDK(Temurin 17.0.20、Homebrew 21.0.12 与 27,每篇注明实际用的版本);用 javac 编译、java 直接运行,需要第三方库时用 Maven 解析依赖;计时用 System.nanoTime,数字每次运行会有小幅抖动。JDK 21.0.12 的 javadoc;示例只有一个类 shop.Order
    • 没有验证:内联 Taglet({@name …})、Maven javadoc 插件里的 tags 与 taglets 配置、JDK 8 的 -tag 语法差异、-tag 的其它位置字符(c、f、o、p)的完整效果、Taglet 在模块化项目里的类路径、HTML 输出的样式与 CSS 定制
    京ICP备2026067502号-1京公网安备11010502063487号