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

chris.jerdonek at gmail.com chris.jerdonek at gmail.com
Sun Nov 25 04:05:18 CET 2012


Reviewers: ezio.melotti,


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
I recommend using the "target" form in cases like this so that the "s"
does not look different from the rest of the word.

http://bugs.python.org/review/15990/diff/6650/Doc/faq/programming.rst#newcode333
Doc/faq/programming.rst:333: arguments are the actual values passed to a
function during a call.
I think it is usually better to start off by stating the difference, and
then following with an example, as opposed to the reverse.

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#newcode46
Doc/glossary.rst:46: * positional arguments: values passed by position
(e.g. ``3`` and ``5``
The singular form should be used here to parallel the singular form
being used elsewhere.  Also, defining "positional" as "passed by
position" seems circular.

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
On 2012/11/22 16:38:14, ezio.melotti wrote:
> Is "passed by keyword" an acceptable terminology?

Similar to above, defining keyword argument to mean "passed by keyword"
seems circular.

http://bugs.python.org/review/15990/diff/6650/Doc/glossary.rst#newcode559
Doc/glossary.rst:559: A named entity in a :term:`function` (or method)
signature that
We can use "definition" in place of "signature," though signature may be
the better word for people who know what it means.  I originally chose
"entity" because "object" is already laden with other meanings in
Python.

Regarding the word "argument," I think it is helpful to reference
because it makes clear the dependency relationship between the two terms
(and the reader can then look up the other term).  Note also that the
entry for argument does not depend on "parameter" for its definition.

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:
On 2012/11/22 16:38:14, ezio.melotti wrote:
>   Named entities in a function (or method) signature that
>   define what :term:`arguments` the function can accept.

We can still use a form like this without pluralizing.  For example,

   A named entity in a function (or method) definition that defines
   an argument (or arguments) that the function can accept.

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

I think the singular form should be used for nouns in the glossary.  The
only exception to this that I can think of is if the singular form is
never or rarely used (e.g. a word like data).  It looks like "universal
newlines" is the only entry that currently ends in "s."  In that case,
the word is used an adjective and so isn't really a counter example. 
Moreover, there we were deciding what term should be used in all cases
(e.g. "universal newline mode" versus "universal newlines mode").

http://bugs.python.org/review/15990/diff/6650/Doc/glossary.rst#newcode577
Doc/glossary.rst:577: * var-positional: a tuple of positional arguments
that aren't bound to
This reads like a var-positional parameter is a tuple of positional
arguments, which isn't what we want to communicated.

http://bugs.python.org/review/15990/diff/6650/Doc/glossary.rst#newcode581
Doc/glossary.rst:581: * var-keyword: a dict of keyword arguments that
aren't bound to any other
This reads like a var-keyword parameter is a dict of keyword arguments,
which isn't what we want to communicate.



Please review this at http://bugs.python.org/review/15990/

Affected files:
  Doc/faq/programming.rst
  Doc/glossary.rst




More information about the docs mailing list