Add arg/return examples to functions

[iandunn]

Right now https://developer.wordpress.org/reference/functions/zeroise/ tries to explain the inputs and returns in the description, but it'd be much easier to read and understand in code.

I think it'd be helpful for functions to have a dedicated Examples section, similar to https://www.php.net/manual/en/function.array-splice.php and https://developer.wordpress.org/cli/commands/cli/

The PHP manual combines all inputs into one section, and the outputs into another, though. I think it'd be easier if the input/output pairs were kept together, like this:

> wp shell

>>> zeroise( 10, 4 )
=> "0010"

>>> zeroise( 10, 3 )
=> "010"

>>> zeroise( 5000, 4 )
=> "5000"

>>> zeroise( 50000, 4 )
=> "50000"

This is related to #23, but I think we should go further and have an entire section, where we can have blocks of code, and prose descriptions. The section could look something like this:

Examples

Individual arguments

prepare() is often called with each un-sanitized value explicitly passed as an individual argument; for example:

$wpdb->prepare( "SELECT id FROM $wpdb->posts WHERE id > %d AND post_status = %s", $min_id, $status )

Array of arguments

The function will also accept an array of un-sanitized values, though, like this:

$wpdb->prepare( "SELECT id FROM $wpdb->posts WHERE id > %d AND post_status = %s", array( $min_id, $status ) )

Dynamic Placeholders

When you have a multi-dimensional array where each sub-array contains a different number of items, you can build the placeholders dynamically:

foreach ( $new_status_post_id_map as $new_status => $wordcamp_ids ) {
	$wordcamp_id_placeholders = implode( ', ', array_fill( 0, count( $wordcamp_ids ), '%d' ) );
	$prepare_values           = array_merge( array( $new_status ), $wordcamp_ids );

	$wpdb->query( $wpdb->prepare( "
		UPDATE `$table_name`
		SET `post_status` = %s
		WHERE ID IN ( $wordcamp_id_placeholders )",
		$prepare_values
	) );
}

So if a sub-array has 2 items, then $wordcamp_id_placeholders will be '%d, %d', and if the next array has 4 items, then its placeholder string would be '%d, %d, %d, %d'.