classification
Title: Make documentation of * in function signatures easier to find
Type: enhancement Stage:
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.araujo, fredg1
Priority: normal Keywords:

Created on 2020-12-04 21:11 by fredg1, last changed 2020-12-14 14:34 by eric.araujo.

Messages (5)
msg382530 - (view) Author: Frederic Gagnon (fredg1) Date: 2020-12-04 21:11
Could be helpful to make it so that, in libraries, / * *<param> and **<param>  (i.e. positional-only, keyword-only, var-positional and var-keyword indicators) link to https://docs.python.org/3/glossary.html#term-parameter

This come from someone relatively new to python that had a somewhat hard time understanding what the ", *," stood for in https://docs.python.org/3/library/glob.html#glob.glob
msg382876 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2020-12-11 18:30
I don’t think every function signature should have links when using `*`, `*args` or `**kwargs`.

Is there another page that we could improve?
What did you search for when you wanted to understand what it means?

Possible candidates: tutorial page about functions; language reference about functions; others?
msg382965 - (view) Author: Frederic Gagnon (fredg1) Date: 2020-12-14 09:08
I didn't know if that "*" was part of python, or just specific to the documentation.

I started by just looking around the page (header, section on the left and footer) for some kind of link pointing to how to interpret the documentation.

Not finding anything, I went up the tree (first to https://docs.python.org/3/library/index.html , then to https://docs.python.org/3/index.html ). I then went to the FAQ ( https://docs.python.org/3/faq/index.html ).
(Little did I know, the answer was in Glossary...)

Not finding any answer there, I tried googling it (simply starting with "python *"), but since * is interpreted as a wildcard, my searches only gave broad results about "python".

I then asked a friend who pointed me to https://stackoverflow.com/questions/51362773/what-does-mean-as-a-parameter-in-python
msg382966 - (view) Author: Frederic Gagnon (fredg1) Date: 2020-12-14 09:12
The information could be added to https://docs.python.org/3/faq/library.html#general-library-questions , leading to links to where to find information about the library's syntax
msg382989 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2020-12-14 14:34
Thank you for the details!  This helps finding a good place to document this.
A link to function parameters from the top of the section may be good.
But maybe we need a sidebar link on all pages that goes to a description of doc conventions! (and includes link to basic syntax doc, function parameter glossary, tutorial).

(As you thought, there are notations in the docs (and even in some docstrings) that are documentation conventions but not valid Python, such as "range(start, stop[, step]) -> range object")

Even the enty for '* (asterisk)' in the general index https://docs.python.org/3/genindex-Symbols.html links to places explaining *args, not * alone.

I agree that the glossary entry for parameter is the best place to link to: it’s short and complete and can link to language reference for more.
History
Date User Action Args
2020-12-14 14:34:02eric.araujosettitle: [docs] add links to Glossary#parameter in libraries -> Make documentation of * in function signatures easier to find
messages: + msg382989
versions: + Python 3.8, Python 3.9, Python 3.10
2020-12-14 09:12:53fredg1setmessages: + msg382966
2020-12-14 09:08:31fredg1setmessages: + msg382965
2020-12-11 18:30:55eric.araujosetnosy: + eric.araujo
messages: + msg382876
2020-12-04 21:11:08fredg1create