如何用 PHPDoc 记录数组键/值的含义？答案

【问题标题】：How to document an array key / value meaning with PHPDoc?如何用 PHPDoc 记录数组键/值的含义？
【发布时间】：2023-03-05 02:50:01
【问题描述】：

我有一个数组，表示字符串之间的一些映射。键和值都具有（业务）意义。例如在数组中：

[
    '10000' => 'f4970340-9cb7-4380-948c-54e0d1556d58',
    '20000' => '665cdd7d-dbef-4c0a-963e-467a68fa097f',
    '84000' => '5b7f0abc-a515-4409-8b70-f1aafeef5038',
    … # more entries
]

10000、20000 和 84000 代表客户。 UUID 代表客户所属的组。

对于如何记录字符串的含义，是否有任何约定/最佳实践？我不是在谈论记录类型（=字符串）。

类似：

    /**
     * @return string[]
     * [
     *     customerId => groupId,
     *     …
     * ]
     */
    public function getCustomerIdGroupIdMap(): array
    {}

【问题讨论】：

标签： php phpdoc

【解决方案1】：

在我见过和使用的所有案例中，text description 是添加特定注释以阐明细节的最佳位置。

<?php

/**
 * Returns an array keyed by the customer ID. The values represent the group ID. 
 * @return array
 */
public function getCustomerIdGroupIdMap(): array
{}

或者，可以使用description of the return type。

<?php

/**
 * @return array Keyed by the customer ID. The values represent the group ID. 
 */
public function getCustomerIdGroupIdMap(): array
{}

【讨论】：