When documenting PHP code with PHPDoc or similar how do you state array name => value pairs?

Question

If I had a function and I currently was passing in the values all as strings and had it documented something like this:

/**
 * Sends mail using the built-in Swift Mailer component
 * @param string $from The email address who it's from
 * @param string $to The email address who we are sending it to
 * @param string $message The text-based message to send
 * @param string $html_msg The html-based message to send
 * @param string $from_name The name of the person/company it is from
 * @param string $to_name The name/company of the person who we are sending it to
 * @param string $reply_to The reply to email address
 * @return bool true or false if sending succeeded
 */

But instead wanted to pass all the below in a single array, how would I document each key correctly?

Answer 1

You should declare the param as an array and, eventually you could describe some details inside a code tag. Something like:

/**
 * Sends mail using the built-in Swift Mailer component
 *
 * Example:
 * <code>
 *
 *    $expectedArray = array(
 *        'from' => 'value',
 *        'to'   => 'another value',
 *        ... 
 *    );
 *
 *    yourfunc($expectedArray)
 *
 * </code> 
 *
 * @param array $yourarray an array bla bla... 
 * @return bool true or false if sending succeeded
 */