Support formatting of documentation for parameters that are arrays

[bobbingwide]

developer.wordpress.org nicely formats @param tags where the parameter type is an array. Each array field is documented once when the array is first defined e.g.

* @param array $args {
 *     Optional. An array of arguments.
 *
 *     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
 *                     (aligned with Description, if wraps to a new line)
 *     @type type $key Description.
 * }

and then it's referenced in all other params via an @see tag.

* @param array $cargs {@see class::method()}
* @param array $fargs {@see function()}

WordPress documentation is here

https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#1-1-parameters-that-are-arrays

The WordPress documentation refers to phpDocumentor standards which uses a slightly different approach. e.g.

* @param array $args {
*     @var bool   $required Whether this element is required
*     @var string $label    The display name for this element
* }

Great! @var instead of @type

BTW: The WordPress documentation mentions something called hash notation. It doesn't describe what hash notation is supposed to be. But it does link to phpDocumentor PSR-5 recommendations... where there is no mention of the term.

Super..

:sarcasm off.

[bobbingwide]

The current solution can't handle a number of things.

• {@see 'hook_name'}
• @type tags with more than one blank between values
• Nested arrays for @type tags
• -- at the start of a line in the description
• @since and @global tags in unexpected places

See http://core.wp-a2z.org/oik_api/register_post_type/ for an example vs. https://developer.wordpress.org/reference/functions/register_post_type/

[bobbingwide]

Note: developer.wordpress.org converts the parameter name in the @type tag from $name to 'name' but in subsequent references uses the $ prefix.

[bobbingwide]

To fix {@see 'hook_name'} we'll replace it with the [hook] shortcode passing a special value of '.' for the second parameter ( type ).

When the value is '.':

1. We won't append the hook_type determined from the database
2. We'll create links even if the hook is not known to the local system.

[bobbingwide]

The solution can't handle ** at the start and end of a line, which should be interpreted as bold markdown.

Example: http://woocommerce.wp-a2z.org/oik_api/remove_accents/ Accent characters converted:

[bobbingwide]

The solution can't handle ** at the start and end of a line, which should be interpreted as bold markdown.

Still doesn’t work. It would appear that oikai_check_its_a_list needs improving for both ** and --. With the check on the previous line being applied at a different time perhaps?