KDoc规范

KDoc语法

• 像 Javadoc 一样，KDoc 注释也以 /** 开头、以 */ 结尾。注释的每一行可以以星号开头，该星号不会当作注释内容的一部分。文档文本的第一段（到第一行空白行结束）是该元素的总体描述，接下来的注释是详细描述。每个块标签都以一个新行开始且以 @ 字符开头。
• 示例：

  /**
   * 一组*成员*。
   *
   * 这个类没有有用的逻辑; 它只是一个文档示例。
   *
   * @param T 这个组中的成员的类型。
   * @property name 这个组的名称。
   * @constructor 创建一个空组。
   */
  class Group<T>(val name: String) {
      /**
       * 将 [member] 添加到这个组。
       * @return 这个组的新大小。
       */
      fun add(member: T): Int { …… }
  }

• 块标签：KDoc目前支持以下标签
  • @param  名称：用于函数的值参数或者类、属性或函数的类型参数。
    • 有以下两种语法

    • @param name 描述。
      @param[name] 描述。

  • @return：用于函数的返回值。
  • @constructor：用于类的主构造函数
  • @receiver：用于扩展函数的接收者
  • @property  名称：用于类中具有指定名称的属性。这个标签可用于在主构造函数中声明的属性，当然直接在属性定义的前面放置 doc 注释会很别扭。
  • @throws  类、@exception  类：用于方法可能抛出的异常。因为 Kotlin 没有受检异常，所以也没有期望所有可能的异常都写文档，但是当它会为类的用户提供有用的信息时， 仍然可以使用这个标签。
  • @sample  标识符：将具有指定限定的名称的函数的主体嵌入到当前元素的文档中， 以显示如何使用该元素的示例。
  • @see  标识符：将到指定类或方法的链接添加到文档的另请见块。
  • @author：指定要编写文档的元素的作者。
  • @since：指定要编写文档的元素引入时的软件版本。
  • @suppress：从生成的文档中排除元素。可用于不是模块的官方 API 的一部分但还是必须在对外可见的元素。
  • 注意：KDoc 不支持 @deprecated 这个标签。作为替代，请使用 @Deprecated 注解。

Demo示例：

• 目前的文件结构：

  /src/main/kotlin/com/zs/usermanagement/
      - User.kt
      - UserManager.kt
      - package-info.kt
      - samples.kt
  /build.gradle.kts
  
  

• fun和class注释：

  package com.zs.usermanagement
  
  /**
   * 表示一个简单的用户类。
   *
   * @property name 用户的姓名
   * @property age 用户的年龄
   * @constructor 创建一个用户实例
   * @see UserManager 用于管理用户的类
   * @since 1.0
   * @author zs
   */
  data class User(val name: String, val age: Int)
  
  /**
   * 获取用户的详细信息。
   *
   * @param user 要获取详细信息的用户
   * @return 用户的详细信息字符串
   * @throws IllegalArgumentException 如果用户的年龄小于 0
   * @see User
   * @sample com.zs.usermanagement.samples.getUserInfoSample
   * @since 1.0
   */
  fun getUserInfo(user: User): String {
      if (user.age < 0) throw IllegalArgumentException("Age cannot be negative")
      return "Name: ${user.name}, Age: ${user.age}"
  }
  

    

  package com.zs.usermanagement
  
  /**
   * 管理用户的类，提供用户注册、登录和获取用户信息的方法。
   *
   * @constructor 创建一个新的 UserManager 实例
   * @see User
   * @since 1.0
   * @suppress
   * @author zs
   */
  class UserManager {
      
      /**
       * 注册一个新用户。
       *
       * @param name 新用户的姓名
       * @param age 新用户的年龄
       * @return 注册的用户对象
       * @throws IllegalArgumentException 如果用户的年龄小于 0
       * @see loginUser 用于用户登录的方法
       * @sample com.zs.usermanagement.samples.registerUserSample
       * @since 1.0
       */
      fun registerUser(name: String, age: Int): User {
          if (age < 0) throw IllegalArgumentException("Age cannot be negative")
          return User(name, age)
      }
  
      /**
       * 模拟用户登录。
       *
       * @param user 要登录的用户
       * @return 登录是否成功
       * @see registerUser 用于用户注册的方法
       * @sample com.zs.usermanagement.samples.loginUserSample
       * @since 1.0
       */
      fun loginUser(user: User): Boolean {
          // 简单模拟登录逻辑
          return user.name.isNotEmpty() && user.age > 0
      }
  }
  

• package注释（package-info.kt）： 

  /**
   * 这个包包含用户管理相关的类和接口。
   *
   * 包含的类：
   * - User
   * - UserManager
   *
   * 包含的函数：
   * - getUserInfo
   *
   * @see User 用于表示用户的类
   * @see UserManager 用于管理用户的类
   * @since 1.0
   * @author zs
   */
  package com.zs.usermanagement
  

• module注释（build.gradle.kts）： 

  /**
   * 这个模块负责用户管理功能，包括用户注册、登录和获取用户信息。
   *
   * 模块依赖：
   * - Kotlin Standard Library
   *
   * @see com.zs.usermanagement.User 用于表示用户的类
   * @see com.zs.usermanagement.UserManager 用于管理用户的类
   * @since 1.0
   * @author zs
   */
  plugins {
      kotlin("jvm") version "1.9.23"
  }
  
  dependencies {
      implementation(kotlin("stdlib"))
  }
  

•  samples.kt：

  package com.zs.usermanagement.samples
  
  import com.zs.usermanagement.User
  import com.zs.usermanagement.UserManager
  
  /**
   * 示例：如何使用 `getUserInfo` 方法。
   */
  fun getUserInfoSample() {
      val user = User("Alice", 30)
      val info = getUserInfo(user)
      println(info)
  }
  
  /**
   * 示例：如何使用 `registerUser` 方法。
   */
  fun registerUserSample() {
      val manager = UserManager()
      val user = manager.registerUser("Bob", 25)
      println(user)
  }
  
  /**
   * 示例：如何使用 `loginUser` 方法。
   */
  fun loginUserSample() {
      val manager = UserManager()
      val user = User("Charlie", 20)
      val success = manager.loginUser(user)
      println("Login successful: $success")
  }
  

Dokka生成KDoc文档 

• 在项目的根构建脚本中应用适用于 Dokka 的 Gradle 插件：

  plugins {
      id("org.jetbrains.dokka") version "1.9.20"
  }

• 在记录多项目构建时，需要 在子项目中应用 Gradle 插件：

  subprojects {
      apply(plugin = "org.jetbrains.dokka")
  }

• 要生成文档，请运行以下 Gradle 任务：

  • dokkaHtml对于单个项目构建
  • dokkaHtmlMultiModule用于多项目构建
  • 默认情况下，输出目录设置为 和 。/build/dokka/html/build/dokka/htmlMultiModule