Remove data types from main function.

[StevenDufresne]

WordPress functions can take numerous arguments and trying to read the function declaration is difficult. We don't need the data types if we have the parameters listed immediately below as presented in #7 and make the data type easier to see as presented in #9.

This will improve:

• Readability
• Copyability

Before	After

[tellyworth]

In addition we could add other cues for parameter types and defaults: colours, icons, font styling, sub/superscript, tooltips. Also applies to #9 .

[dd32]

I'm of two minds here.

1. I'm not 100% certain how common the parameter-level documentation clearly communicates the defaults. BUT it's also not uncommon for the function syntax defaults to not expose the result of those defaults, ie. WHAT happens when $post is left as the default 0? Usually that means it uses the current post object, but other parameters don't always default like that.
2. The function syntax is super useful to provide which fields are optional, and which are required. Scanning across a list of parameters and seeing = '' is a lot quicker than reading through the parameter data looking for whether a default is specified.

[ryelle]

I find that first line to be more like a heading/summary of the function, since it has the parameter names and types. By looking at it I know what values the function takes, and I maybe don't even need to read down to the rest of the page. So I'm not in favor of removing the data types/defaults.

[iandunn]

Yeah, I use it that way too.

[tellyworth]

What do you think of the idea of abbreviating the data types and defaults?

[renintw]

At first, I found it hard to read the main function with such format, though I eventually got used to it, I still feel a bit hmm... seeing it from time to time.

I'm thinking that since the Parameter section in the current page layout isn't right below the main function, it would be not easy to refer to what values the function takes easily. So if we can make sure the Parameter section and the main function are displaying at the same time or without requiring too much scrolling to refer to parameters, I think it would be nice to remove the data type from the main function to increase the readability.
Here are two examples:
https://nodejs.org/dist/latest-v18.x/docs/api/path.html#pathparsepath
https://redux.js.org/api/createstore

We probably could remove the data types after making sure that we (just like what Steve mentioned above)
a) Move the Parameters section up #7
b) Make the content in Paramteres clear #9

Or, if we eventually decided not to remove the data types, I'm wondering if it's a good idea to reformat the main function section.
We can probably do
a) Abbreviate the data types and defaults. (Mentioned by Alex above)
b) Make it just one line.
c) (Personal opinion) Don't italicize the data types.
Exmaple: https://www.php.net/manual/en/function.print-r.php