[Converted to Issue] The first code block should be a copyable example.

[StevenDufresne]

We should prefer copyable code blocks over function definitions. While users can already copy the function definitions, maybe because of the datatypes or because it doesn't look like a code block, it isn't apparent that I can use that line of code.

By removing the argument names, and optional parameters and giving the block more visual preference, we have a block of code that is easy to copy and paste into your own environment.

Before	After

Note: I've switched the description and parameters section. Related: #9 #7

[iandunn]

I think this is great; examples are usually a better starting point for me than the full spec.

I think it's important to show multiple, though, like:

activate_plugin( 'my-plugin/bootstrap.php' );
activate_plugin( 'my-plugin/bootstrap.php', '', true ); // network-wide
activate_plugin( 'my-plugin/bootstrap.php', admin_url( 'my-special-activation-page' ), false, true ); // uncommon behavior

[iandunn]

phpDoc has an @example tag that could be useful for this

[iandunn]

...that's intended to work with external files, though, which is weird. WP-CLI just uses a mix of markdown and phpDoc in their generated docs:

https://github.com/wp-cli/wp-cli/blob/4b446e100398c5774bf2a244f69465ccd65deaa8/php/commands/src/CLI_Command.php#L9-L34

gets parsed to: https://developer.wordpress.org/cli/commands/cli/