The first code block should be a copyable example.

[tellyworth]

Discussed in https://github.com/WordPress/wporg-developer/discussions/12

^{Originally posted by StevenDufresne May 23, 2022} 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: https://github.com/WordPress/wporg-developer/discussions/9 https://github.com/WordPress/wporg-developer/discussions/7

[StevenDufresne]

Huddle Chat Notes:

• Completing https://github.com/WordPress/wporg-developer/issues/25 first is probably a good start (using syntax plugin)
• Current format matches PHP documentation
• We also need to agree on https://github.com/WordPress/wporg-developer/discussions/8 first.

[iandunn]

using syntax plugin

which one?

[StevenDufresne]

using syntax plugin

which one?

Looking at those notes 24hrs removed,.... I'm not quite sure what I meant (transcribed from the conversation). I assume it was just mentioning that we probably want to improve styles with the current plugin if possible.

[ryelle]

Copying over some comments from https://github.com/WordPress/wporg-developer/pull/59

https://github.com/WordPress/wporg-developer/pull/59#issuecomment-1145535710

in the function reference, the title/headline represents the code I should write in order to use the function, more or less. Whereas with the hooks, the headline represents the code core uses to call the hook, not the code I should write.

Perhaps both of these would be solved by having a one-line example immediately below the headline for every function, hook, etc. Something like:

apply_filters( 'pre_wp_filesize', ... )

add_filter( 'pre_wp_filesize', 'example_callback', 10, 2 );

..where the example line is syntax highlighted and easily copyable. We could also allow multiple examples, ref https://github.com/WordPress/wporg-developer/discussions/12#discussioncomment-2807259

https://github.com/WordPress/wporg-developer/pull/59#issuecomment-1145709425

with #12 in mind, this would work well for hooks IMHO, but I'd expand that to have the function in there too:

add_filter( 'pre_wp_filesize', 'example_callback', 10, 2 );
function example_callback( $param1, $param2 ) {
    return $param1;
}