Skip to content

Commit da1b11a

Browse files
committed
explain more about the reason to use slash/star
1 parent 672ceb9 commit da1b11a

File tree

1 file changed

+7
-1
lines changed

1 file changed

+7
-1
lines changed

documentation/style-guide.rst

Lines changed: 7 additions & 1 deletion
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
========
@@ -295,9 +296,14 @@ making false assumptions about the language ("I was surprised by ...").
295296
Function signatures
296297
===================
297298

298-
These are the evolving guidelines for how to include function signatures in the docs:
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.
299302

300303
- If a function accepts positional-only or keyword-only arguments, include the
301304
slash and the star in the signature as appropriate::
302305

303306
.. 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)