如何为多个类方法中名为p的内置类型参数编写文档？

1. 直接在方法注释中明确描述 #

针对每个包含p参数的方法，在文档注释里直接说明其类型和业务用途，示例如下：

class A {
  /**
   * 执行初始化操作
   * @param p 键值对映射，类型为`Map[String, String]`，用于存储初始化配置项
   */
  def init(p: Map[String, String]): Unit = {}
}

class B {
  /**
   * 执行数据处理操作
   * @param p 键值对映射，类型为`Map[String, String]`，用于传递数据过滤规则
   * @param timeout 处理超时时间（毫秒）
   */
  def process(p: Map[String, String], timeout: Int): Unit = {}
}

这种方式直观直接，适合p在不同方法中用途略有差异的场景，能让每个方法的文档独立清晰。

2. 定义带文档的类型别名 #

如果Map[String, String]在你的业务中有固定含义，先定义一个类型别名并为其添加完整文档，之后所有方法都使用这个别名，只需维护一处文档即可：

/**
 * 字符串键值对配置映射，用于存储各类字符串类型的配置项，键为配置名称，值为配置内容
 */
type StringConfigMap = Map[String, String]

class A {
  /**
   * 执行初始化操作
   * @param p 初始化配置映射，具体定义参考`StringConfigMap`
   */
  def init(p: StringConfigMap): Unit = {}
}

class B {
  /**
   * 执行数据处理操作
   * @param p 过滤规则映射，具体定义参考`StringConfigMap`
   * @param timeout 处理超时时间（毫秒）
   */
  def process(p: StringConfigMap, timeout: Int): Unit = {}
}

这种方式能统一类型的含义描述，后续修改只需更新类型别名的注释，所有引用的方法文档都会间接同步。

3. 复用文档片段（依赖文档工具支持） #

如果你的文档生成工具（比如Scala的Scadoc）支持复用注释片段，可以把p的标准描述抽成可复用的片段，在各个方法中引用：

// 定义可复用的文档片段
/** @define configParam 键值对映射，类型为`Map[String, String]`，用于传递业务配置信息 */

class A {
  /**
   * 执行初始化操作
   * @param p $configParam
   */
  def init(p: Map[String, String]): Unit = {}
}

class B {
  /**
   * 执行数据处理操作
   * @param p $configParam
   * @param timeout 处理超时时间（毫秒）
   */
  def process(p: Map[String, String], timeout: Int): Unit = {}
}

这种方式适合所有p参数的含义完全一致的场景，能大幅减少重复编写文档的工作量。

内容的提问来源于stack exchange，提问作者Gradle Trampled