[docs] [issue12531] documentation index entries for * and **

Terry J. Reedy report at bugs.python.org
Mon Jul 18 21:14:08 CEST 2011

Terry J. Reedy <tjreedy at udel.edu> added the comment:

I would not propose to do everything in one grand patch as it would be way too much to review all at once. A somewhat separate subissue is whether there should be however many separate issues over the next however many years or one master issue with multiple patches.

The existing patch is enough to review for now. It needs changes and should add everything needed just for * and **. And there may be some unwritten policy issues.

I agree that the directive for * should be moved as Eli says.
I think 'statement' should be changed to 'function calls', or maybe 'in function calls' or 'function call operator' for both * and **.
The same directives should be added to the tutorial at the top and middle of Tutorial 4.7.4 Unpacking Argument Lists.
The existing * and ** 'statement' directives for defs in both tutorial and reference should become 'function defs' (or 'definitions') or 'in def statement'.
The existing * 'operator' directive should be 'number multiplication' or 'number multiplication operator' or at least 'number operator'.
Perhaps it (and the following) should be duplicated in the tutorial.
A new * 'sequence repetition* directive should be added.
The existing ** 'operator' directive should be 'number exponentiation'.
New 'assigment' and 'import' directives are needed.

I think *all* the entries for a given symbol should be considered together so that they can be properly differentiated. We should minimize duplicates that appear like this -- 'statement, [1]' -- and such duplicates should refer to the *same* usage. 

Policy issues:

I think 'statement' should be reserved for statement keywords like def, class, etc. Things in statements should be at least qualified as 'in <specific> statement.

I see that plain 'operator' is currently used for most or all operators. I think they should at least be qualified as to category -- number operator, seqeunce operator, comparision operator, logic operator, etc. This might tell users all they need to know and would separate overloaded operators like '*'.

Both general suggestions follow other usages. Classes are specified as 'class in <modname>', not just 'class'. Functions are specified not just with '()' but also 'in <modname>' Expanding 'statement' to 'in <keyword> statement' or something would be in the same spirit. Methods are specified as '<class> method', not just 'method'. Operators should get the same differentiation with at least '<optype> operator' if not more detail.

[separate issue note: 'as' seems not to be indexed.]

Adding Georg as I am suggesting a deviation from certain precedents (and conformance to others).

nosy: +georg.brandl
stage:  -> patch review

Python tracker <report at bugs.python.org>

More information about the docs mailing list