How to document an array key / value meaning with PHPDoc?

Question

I have an array that represents some mapping between strings. The key and the value both have (business) meaning. For example, in the array:

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

10000, 20000 and 84000 represent customers. The UUIDs represent groups to which the customers belong.

Is there any convention / best-practice of how to document the meaning of the strings? I am not talking about documenting the types (=strings).

Something like:

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

waterloomatt · Accepted Answer · 2020-09-15 14:05:32Z

1

In all the cases I've seen and used, the text description is the best place to add specific notes to clarify the details.

<?php

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

Alternatively, using the description of the return type can be used.

<?php

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

edited Sep 15, 2020 at 14:05

answered Sep 15, 2020 at 14:00

waterloomatt

3,7731 gold badge23 silver badges28 bronze badges

Sign up to request clarification or add additional context in comments.

Collectives™ on Stack Overflow

How to document an array key / value meaning with PHPDoc?

1 Answer 1

Comments

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Related