Slash notation should be defined in a notation key at the beginning of the Built-In Functions section

[dbooth-boston]

Documentation

The Standard Library defines a number of built-in functions, and a shorthand notation is used when a function is defined, such as the definition of repr:

repr(object, /)

But there is no information about what that "/' means in the function signature. It is not standard computer science notation, so I started looking for its meaning. Normally, a notation key should be at the beginning of the document or section, but I do not find a notation key either at the beginning of the section or at the beginning of the documentation.

Could a notation key be added please, to define the meaning of this and any other non-standard notation that is used in the Python documentation?

[pochmann]

See Function definitions.

[StanFromIreland]

This has been implemented, on hover the text "Positional-only parameter separator" appears.

[AA-Turner]

Hover doesn't work on mobile.

A

[XChaitanyaX]

I think they should be defined in the function definitions section and not in the built-in functions as this section just says how the built-in functions work.

cpython/Doc/reference/compound_stmts.rst

Lines 1325 to 1328 in 074f3b2

	new empty mapping of the same type. Parameters after "``*``" or
	"``*identifier``" are keyword-only parameters and may only be passed
	by keyword arguments. Parameters before "``/``" are positional-only parameters
	and may only be passed by positional arguments.

And of course they are defined in the function definitions section

And they are also present in the tutorial here

[tartley]

And of course they are defined in the function definitions section

Perhaps we should make it easier for newcomers to find that? Perhaps the start of Built-in Functions could add a short sentence, perhaps between the initial table of function names and the first definition, reading something like:

The syntax used in these definitions is explained in function definitions.

But this irks me slightly in that the function definitions page describes the function definition syntax, whereas the builtins page is showing an illustrative function call syntax (e.g. without the 'def'.)

(Forgive the newb drive-by. Looking for a first issue.)

[tartley]

Perhaps the link I propose could narrow down the referenced part of 'function definitions' by linking directly to the relevant text:

The syntax used in these definitions is explained in function definitions.

Then we're linking to the description of '*' and '/', not to the whole function declaration syntax, parts of which are extraneous here.

Problems with this: It does make the link brittle to changes in the referenced text. And my current example highlights only the description of * and /, excluding the description of the forms *args, **kwargs, and param=value. Expanding the section to include these would include more than a screenful of text, covering most of the section. Perhaps it's best to just link to the "function-definitions" heading after all.

[XChaitanyaX]

Perhaps we should make it easier for newcomers to find that? Perhaps the start of Built-in Functions could add a short sentence, perhaps between the initial table of function names and the first definition, reading something like:

Newcomers already have the tutorial. If we really want to add a link(in the built-in section), then maybe we should hyperlink it to the tutorial.

[tartley]

If we really want to add a link(in the built-in section), then maybe we should hyperlink it to the tutorial.

OK, thanks for the input. So it sounds to me like the alternatives we face are either:

1. Add a sentence to the start of Built-in Functions, between the initial table of function names and the first definition, which links to the relevant tutorial section, something like:

The syntax used in these definitions is explained in the tutorial.

or

2. Do nothing, and close this issue, since there is now explanatory text displayed on hover over the relevant symbols, although hover text doesn't work on mobile.

Does that seem right?

[dbooth-boston]

Option 1 sounds great to me. Though I think and even better enhancement -- call it option 1.a. -- would be to add a brief synopsis of the notation at the start of the Built-in Functions page, with a link to the tutorial for details. Maybe something roughly like this (though I'm sure I don't have the formatting quite right):

== Notation ==

Function signatures below use the following notation, which is further described in the tutorial[link].

 = -- round(number, ndigits=None)
  The default value of ndigits is None.

 / -- class int(string, /, base=10)
  Parameters before "/" are positional-only; others are positional-or-keyword.

 * -- exec(source, /, globals=None, locals=None, *, closure=None)
  All parameters after "*" are keyword-only.

 ** -- class dict(iterable, /, **kwargs)
   kwargs receives a dictionary of all keyword arguments except those corresponding to a formal parameter, i.e., all except iterable.

 * with ** -- cheeseshop(kind, *args, **kwargs)
  All positional arguments after kind are passed as a tuple to args, and kwargs receives all other keyword arguments.