[docs] solidify argument/parameter terminology (issue 15990)

ezio.melotti at gmail.com ezio.melotti at gmail.com
Thu Nov 22 16:38:14 CET 2012


http://bugs.python.org/review/15990/diff/6650/Doc/faq/programming.rst
File Doc/faq/programming.rst (right):

http://bugs.python.org/review/15990/diff/6650/Doc/faq/programming.rst#newcode324
Doc/faq/programming.rst:324: we can say that *foo*, *bar* and *kwargs*
are :term:`parameter`\s of
If we use the plural forms for the glossary entries we won't need the
\s.

http://bugs.python.org/review/15990/diff/6650/Doc/faq/programming.rst#newcode336
Doc/faq/programming.rst:336: How do I write a function with output
parameters (call by reference)?
Not sure this should be called "parameters" :)

http://bugs.python.org/review/15990/diff/6650/Doc/glossary.rst
File Doc/glossary.rst (right):

http://bugs.python.org/review/15990/diff/6650/Doc/glossary.rst#newcode52
Doc/glossary.rst:52: * keyword arguments: values passed by keyword and
assigned to the local
Is "passed by keyword" an acceptable terminology?
Should I add "(e.g. ``keyword=value``) or is it clear from the other
example?

http://bugs.python.org/review/15990/diff/6650/Doc/glossary.rst#newcode55
Doc/glossary.rst:55: A dictionary preceded by ``**`` can also be used to
pass a mapping of
IIRC there were some problems with arbitrary mappings, so I'm not sure
if here "dictionary" should be replaced with "mapping".

http://bugs.python.org/review/15990/diff/6650/Doc/glossary.rst#newcode62
Doc/glossary.rst:62: variables.  Also see the :term:`parameter` glossary
entry and :pep:`362`.
This should link to the FAQ.

http://bugs.python.org/review/15990/diff/6650/Doc/glossary.rst#newcode561
Doc/glossary.rst:561: function can accept.  There are five types of
paramters:
The first sentence is a bit confusing IMHO.
It talks about named entities and function signatures (reader might not
know what they are), and argument and collections of arguments (might
add confusion between parameters/arguments).
OTOH it's difficult to come up with a different wording.
One thing that can be improved is using "defines" instead of
"corresponds", but that would require to pluralize the term and use
something like:
parameters
  Named entities in a function (or method) signature that
  define what :term:`arguments` the function can accept.

Using the plural form might be better if :term:`parameters` is more
common than :term:`parameter`.

http://bugs.python.org/review/15990/diff/6650/Doc/glossary.rst#newcode561
Doc/glossary.rst:561: function can accept.  There are five types of
paramters:
I made a typo: s/paramters/parameters/.
Also here I used "types", whereas in the "argument" entry I used
"kinds".  This should be fixed (I think I prefer "types").

http://bugs.python.org/review/15990/diff/6650/Doc/glossary.rst#newcode579
Doc/glossary.rst:579: function signature (e.g. *args* in ``def
func(*args, **kwargs): ...``).
I was going to use *\*args*, but the actual parameter is only *args*,
same for kwargs/**kwargs in the next example.

http://bugs.python.org/review/15990/diff/6650/Doc/glossary.rst#newcode583
Doc/glossary.rst:583: signature (e.g. *kwargs* in ``def func(*args,
**kwargs): ...``).
This definitions are adapted from the ones in PEP 362.

http://bugs.python.org/review/15990/diff/6650/Doc/glossary.rst#newcode583
Doc/glossary.rst:583: signature (e.g. *kwargs* in ``def func(*args,
**kwargs): ...``).
Do we need an entry for function signature?

http://bugs.python.org/review/15990/diff/6650/Doc/glossary.rst#newcode587
Doc/glossary.rst:587: :pep:`362`.
This should link to the FAQ.

http://bugs.python.org/review/15990/


More information about the docs mailing list