如何为Array<Hash>类型的参数正确记录每个Hash元素的键？

在Ruby的YARD注释体系里，确实没有专门针对Array<Hash>的专属标签，但可以通过以下几种实用方式，清晰记录数组内每个哈希元素的键、类型及说明：

1. 在@param描述中直接用列表说明 #

直接在参数的描述部分，用列表逐条列出每个哈希包含的键、对应类型和业务含义，直观易懂：

# @param [Array<Hash>] work_logs 工作日志元素数组，每个哈希包含以下键：
#   - `:user_id` [Integer] 唯一标识用户的ID
#   - `:task` [String] 具体执行的任务内容
#   - `:duration` [Float] 任务耗时（单位：小时）
#   - `:logged_at` [DateTime] 日志记录的时间

2. 用宏定义哈希结构后复用 #

如果这个哈希结构在多个方法中用到，可以用@!macro提前统一定义，再在@param描述中引用，避免重复编写：

# @!macro work_log_hash
#   @option opts [Integer] :user_id 用户唯一ID
#   @option opts [String] :task 任务内容描述
#   @option opts [Float] :duration 任务耗时（小时）
#   @option opts [DateTime] :logged_at 日志创建时间

# @param [Array<Hash>] work_logs 工作日志元素数组，每个元素都是符合{@macro work_log_hash}结构的哈希

3. 结合@example展示完整结构 #

用示例代码展示数组的实际格式，让使用者一眼就能看懂每个哈希的组成和取值方式：

# @param [Array<Hash>] work_logs 工作日志元素数组，每个哈希包含用户ID、任务、耗时等必填/可选键
# @example 合法的work_logs参数示例
#   [
#     { user_id: 101, task: "优化接口性能", duration: 3.0, logged_at: DateTime.parse("2024-05-20 14:30") },
#     { user_id: 102, task: "编写单元测试", duration: 1.5, logged_at: DateTime.parse("2024-05-20 16:00") }
#   ]

这些方法都能清晰传达Array<Hash>类型参数的内部结构，团队成员或后续维护者看注释就能明确参数要求。

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