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

Question

我有一个数组，它表示字符串之间的一些映射。密钥和价值都具有(商业(意义。例如，在阵列中：

[
'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
{}

Answer 1

在我见过和使用过的所有案例中，文本描述是添加特定注释以澄清细节的最佳位置。

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

或者，也可以使用返回类型的描述。

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