[docs] [issue34118] Fix some class entries entries in 'Built-in Functions'

[Terry J. Reedy]

New submission from Terry J. Reedy <tjreedy at udel.edu>:

The Library Reference 'Built-in Functions' chapter includes build-in classes because classes are functions in the sense of being callable with arguments and returning objects.  A proposal to change the name to Built-in Functions and Classes was rejected (by Raymond, as I remember).
I suspect that 'Built-in Callables' has also been proposed.
  
Some of the current entries need one or both of two fixes. 

1. Most, but not all, of the classes are tagged with '*class*' before the class name.  Classes classmethod and staticmethed are instead tagged with '@' since they are mostly used as decorators, although property is tagged *class*.

Classes enumerate, filter, map, memoryview, range, reversed, tuple, and zip are untagged.  I think, to be consistent, that they should all get the *class* tag.

2. Nearly all entries fully describe the arguments and return values.  The exceptions are those for 6 collection classes. The first 3 have an abbreviated description of the result and a reference for further details on the relationship of input to result.

 class dict(iterable, **kwarg)
    Create a new dictionary. The dict object is the dictionary class. See dict and Mapping Types — dict for documentation about this class.
    For other containers see the built-in list, set, and tuple classes, as well as the collections module.

class frozenset([iterable])
    Return a new frozenset object, optionally with elements taken from iterable. frozenset is a built-in class. See frozenset and Set Types — set, frozenset for documentation about this class.
    For other containers see the built-in set, list, tuple, and dict classes, as well as the collections module.

class set([iterable])
    Return a new set object, optionally with elements taken from iterable. set is a built-in class. See set and Set Types — set, frozenset for documentation about this class.
    For other containers see the built-in frozenset, list, tuple, and dict classes, as well as the collections module.

The next 3 replace 'Return a ___' with 'Rather than being a function'.  (This is from Nick's patch 6 years ago.  https://github.com/python/cpython/commit/83c0ae5de642145ec225d29e7b239aa410229539.)  I object to this because it is wrong if one uses the broad definition of function used in the chapter title.  It is also wrong in the implication there is anything special about these classes in regard to being functions verses classess.  

class list([iterable])
    Rather than being a function, list is actually a mutable sequence type, as documented in Lists and Sequence Types — list, tuple, range.

range(start, stop[, step])
    Rather than being a function, range is actually an immutable sequence type, as documented in Ranges and Sequence Types — list, tuple, range.

tuple([iterable])
    Rather than being a function, tuple is actually an immutable sequence type, as documented in Tuples and Sequence Types — list, tuple, range.

I propose that the 2nd 3 follow the model of the 1st 3, except that the final line should be: "For other collections see the built-in range, tuple, list, frozenset, set, and dict classes, as well as the collections module." (with 1 of the 6 omitted as appropriate).  (Range represents a collection, but is not a container in the sense that the others are.)

----------
assignee: docs at python
components: Documentation
messages: 321674
nosy: docs at python, ncoghlan, rhettinger, terry.reedy
priority: normal
severity: normal
stage: needs patch
status: open
title: Fix some class entries entries in 'Built-in Functions'
type: behavior
versions: Python 3.6, Python 3.7, Python 3.8

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue34118>
_______________________________________