Editorial: make introductions for built-in functions use consistent wording

[bakkot]

There are a good number of different phrasings we use when introducing built-in functions, some of which I've documented here.

We should be more consistent.

[michaelficarra]

My preferred phrasing is

The <name of function as written in header> <{function,method}> performs the following steps when called:

If we want an additional informative description of the function's purpose, it can precede the phrase

It performs the following steps when called:

instead.

[bakkot]

Works for me.

I'd also be fine with listing the arguments as we do for AOs, but I can see the argument for not doing so: AOs are only ever called with the correct number of arguments, so when we speak of them being called with a particular number of arguments we are covering all possible cases, whereas these can in fact be called with any number of arguments and should follow the specified behavior regardless.

[michaelficarra]

We also use "Its get accessor function performs the following steps:".

[jmdyck]

Note that PR #2592 addresses this, among other things.

[michaelficarra]

@jmdyck Can you put "Fixes #XXX" or "Closes #XXX" in your PR descriptions so they link properly?

[jmdyck]

"descriptions" plural?

[michaelficarra]

@jmdyck The descriptions of any PRs you either have open or open in the future.

[jmdyck]

I didn't create #2592 to address this issue. When I submitted #2592, this PR was 9 months in the past, and I'd forgotten about it until an hour ago. Moreover, nobody else commenting on #2592 (or on issue #2576 that preceded it) brought up this issue, so I'm guessing they'd forgotten about it too. I can't promise to remember, now and in the future, every open issue that might be relevant to a PR, but I'm happy to make connections in my PRs if someone else remembers a relevant issue and brings it to my attention.

[michaelficarra]

@jmdyck Of course, I don't expect you to go through every single open issue. Just when you become aware of them. Though performing a search for relevant issues or duplicates before opening a PR is usually a good practice.

[ptomato]

@michaelficarra @bakkot Is the wording suggested in #2304 (comment) with its two variations now the official editors' guidance, or does it need to be discussed further?

[michaelficarra]

@ptomato You can follow the phrasing used in #2592. Plan is to merge that soon largely unchanged.