Skip to content

Commit 6ee39a9

Browse files
authored
Function signatures should use slash/star as needed (#1344)
* Function signatures should use slash/star as needed * explain more about the reason to use slash/star
1 parent efa3c68 commit 6ee39a9

File tree

1 file changed

+16
-0
lines changed

1 file changed

+16
-0
lines changed

documentation/style-guide.rst

+16
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,7 @@ such as "for example" or "that is."
9999

100100

101101
.. index:: diataxis
102+
.. _diataxis:
102103

103104
Diátaxis
104105
========
@@ -291,3 +292,18 @@ errors ("I made a mistake, therefore the docs must be wrong ..."). Typically,
291292
the documentation wasn't consulted until after the error was made. It is
292293
unfortunate, but typically no documentation edit would have saved the user from
293294
making false assumptions about the language ("I was surprised by ...").
295+
296+
Function signatures
297+
===================
298+
299+
These are the evolving guidelines for how to include function signatures in the
300+
reference guide. As outlined in :ref:`diataxis`, reference material should
301+
prioritize precision and completeness.
302+
303+
- If a function accepts positional-only or keyword-only arguments, include the
304+
slash and the star in the signature as appropriate::
305+
306+
.. function:: some_function(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
307+
308+
Although the syntax is terse, it is precise about the allowable ways to call
309+
the function and is taken from Python itself.

0 commit comments

Comments
 (0)