[docs] [issue15990] solidify argument/parameter terminology

Ezio Melotti report at bugs.python.org
Wed Nov 21 16:18:09 CET 2012

Ezio Melotti added the comment:

On one hand it's good to have individual entries that can be referenced.
On the other hand I think it's important that people get the full picture, and having these definitions sparse in 4 or more distinct glossary entries doesn't help IMHO -- even if the reader follows all the cross-links.

I think it would be better to have a single entry somewhere (e.g. in the FAQs -- maybe it's too "advanced" for the tutorial), that:
  * explains the difference between arguments (what you pass) and parameters (what the function accepts);
  * lists the 5 kinds of parameters, providing an example for each;
  * lists the 2 kinds of arguments, providing an example for each;

I see 3 options here:
  1) we make this section and keep stub entries that link to it;
  2) we repeat the informations in both places (section and entries);
  3) we just keep the glossary entries;

If we pick 1 people might have to follow one more link.  Having a single "parameters and arguments" entry in the glossary might make this better by avoiding a redirect.
If we pick 2 there's duplication, and that's bad.
If we pick 3 I think we could at least explain the kinds of arguments in the "argument" entry and having stubs for "keyword args" and "positional args".  This will leave us with only two entries ("argument" and "parameter"), and with the initial problem that we don't know where to put the explanation of the difference between the two (in both? in a new entry? somewhere else? no parallel?).


Python tracker <report at bugs.python.org>

More information about the docs mailing list