Skip to content

Function signatures should use slash/star as needed #1344

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 12, 2024
Merged

Function signatures should use slash/star as needed #1344

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
672ceb9
Function signatures should use slash/star as needed
nedbat Jul 2, 2024
da1b11a
explain more about the reason to use slash/star
nedbat Jul 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions documentation/style-guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@ such as "for example" or "that is."


.. index:: diataxis
.. _diataxis:

Diátaxis
========
Expand Down Expand Up @@ -291,3 +292,18 @@ errors ("I made a mistake, therefore the docs must be wrong ..."). Typically,
the documentation wasn't consulted until after the error was made. It is
unfortunate, but typically no documentation edit would have saved the user from
making false assumptions about the language ("I was surprised by ...").

Function signatures
===================

These are the evolving guidelines for how to include function signatures in the
reference guide. As outlined in :ref:`diataxis`, reference material should
prioritize precision and completeness.

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

.. function:: some_function(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):

Although the syntax is terse, it is precise about the allowable ways to call
the function and is taken from Python itself.
Loading