Gradle项目Javadoc编写规范指南

Gradle项目Javadoc编写规范指南

gradle Adaptable, fast automation for all 项目地址: https://gitcode.com/gh_mirrors/gr/gradle

前言

在Gradle项目中，良好的Javadoc文档是代码可维护性的重要保障。本文将详细介绍Gradle项目中Javadoc的编写规范，帮助开发者编写出专业、一致的API文档。

基础格式规范

基本结构

Javadoc注释块应采用以下标准格式：

/**
 * 返回可在屏幕上绘制的Image对象。
 * <p>
 * url参数必须指定一个绝对{@link URL}。
 * name参数是相对于url参数的说明符。
 * 无论图像是否存在，此方法都会立即返回。
 *
 * @param url 提供图像基础位置的绝对URL
 * @param name 相对于url参数的图像位置
 * @return 指定URL处的图像
 * @see Image
 */
public Image getImage(URL url, String name) {
   try {
       return getImage(new URL(url, name));
   } catch (MalformedURLException e) {
       return null;
   }
}

关键格式要点：

1. 以/**开始注释
2. 第一句话是摘要说明
3. 使用<p>标签分隔段落
4. 描述部分与标签组之间空一行
5. 标签按固定顺序排列
6. 以*/结束注释

HTML标签使用

Javadoc支持有限的HTML标签子集，推荐优先使用以下标签：

• 段落：<p>
• 强调：<em>
• 列表：<ul>, <ol>, <li>
• 标题：<h1>-<h4>
• 链接：<a>

特别提示：<p>和<li>标签可以省略闭合标签。

内容编写规范

摘要片段

摘要片段是Javadoc中最重要的部分，它是方法或类的简短描述，会出现在索引和提示中：

/**
 * 返回可在屏幕上绘制的Image对象。
 */

编写要点：

• 简明扼要
• 以动词开头（对于方法）
• 以句点结束

参数说明

使用@param标签描述参数：

/**
 * @param url 提供图像基础位置的绝对URL，必须
 *            以http或https开头
 * @param name 相对于url参数的图像位置
 */

多行描述时，续行缩进4个空格。

返回值说明

使用@return标签描述返回值：

/**
 * @return 指定URL处的图像，如果URL无效则返回null
 */

异常说明

使用@throws或@exception标签：

/**
 * @throws MalformedURLException 如果URL格式无效
 */

代码示例

内联代码

使用{@code ...}标记代码元素：

/**
 * 使用{@code Project}实例配置项目。
 */

代码块

多行代码示例使用<pre>{@code ...}</pre>：

/**
 * <pre>{@code
 * project.ext.prop1 = "foo"
 * task doStuff {
 *     ext.prop2 = "bar"
 * }
 * }</pre>
 */

带语法高亮的代码块

可以添加语言类实现语法高亮：

/**
 * <pre><code class="language-groovy">
 * defaultTasks('some-task')
 * reportsDir = file('reports')
 * </code></pre>
 */

标签使用顺序

Gradle项目中Javadoc标签应按照以下顺序排列：

1. @param - 方法参数说明
2. @return - 返回值说明
3. @throws - 异常说明
4. @see - 相关参考
5. @since - 引入版本
6. @deprecated - 弃用说明
7. @apiSpec - API规范要求
8. @apiNote - API使用说明
9. @implSpec - 实现要求
10. @implNote - 实现说明

特殊字符处理

在Javadoc中，特殊字符应使用HTML实体：

• < → <
• > → >
• & → &

IDE注意事项

IntelliJ IDEA

1. 会将<p>或空*行显示为换行
2. 可以在设置中关闭HTML标签自动补全

Android Studio

Android Studio不会显示<p>标签后的内容，因此摘要片段应包含足够信息。

最佳实践

1. 为所有public类型和成员编写Javadoc
2. 保持描述简洁但完整
3. 使用一致的术语
4. 及时更新文档以反映代码变更
5. 为复杂逻辑提供充分的示例

通过遵循这些规范，可以确保Gradle项目的API文档保持高质量和一致性，便于开发者理解和使用。

gradle Adaptable, fast automation for all 项目地址: https://gitcode.com/gh_mirrors/gr/gradle