list(), tuple() should not place at "Built-in functions" in documentation

[Terry Reedy]

On 7/19/2011 2:52 AM, Raymond Hettinger wrote:
> On Jul 14, 6:21 pm, Inside<fancheyuj... at gmail.com>  wrote:
>> As telling in the subject,because "list" and "tuple" aren't
>> functions,they are types.Is that right?

They are not instances of a class whose definition name includes the 
word 'Function'. They *are* things that can be called with the call 
operator () (because they have __call__ methods) and that, when called, 
map input objects to output objects. That is the mathematical notion of 
a function. It is also one thing that makes classes different from 
modules, which cannot be called. Classes *also* have other behaviors 
that functions do not, but that does not make them non-functions. Doing 
things besides programming Python does not make one not a Python programmer.

> list() and tuple() are in the right place in the documentation
> because they would be harder to find if listed elsewhere.   Tools
> like str(), int(), list(), tuple() etc tend to be used like
> functions, so the current location in the docs is where they have
> been for years.

The location of anything (that is not missing from the index, which is a 
bug) is easily discovered using the index.

> A simple fact of documentation that is that tools don't always fall
> cleanly into distinct categories.

This is more like a fact of life above the atomic level. As the number 
of things classified grows, most classifications tend to become 
controversial.

>  Accordingly, the Library  Reference
 > includes str,int,list,tuple, etc in both Section 2 for
> builtin functions and Section 5 for builtin types.

Chapter 5 is mostly about the behavior of built-in class instances.  For 
some classes, like range, instances only come from class calls and the 
behavior of instances is intimately tied to the constructor arguments. 
Having the constructor described in C.5 might be useful. For others, 
like int, instances come from many sources and the behavior of instances 
only depends on the resulting value and not the source. Ints can come 
from literals, computation, and int calls with int, other number, or 
string objects. The allowed argument issues for int calls are quite 
separate from using int, so it really belongs in C.2.

I agree that it is best to list all named built-in classes in C.2 with 
appropriates links to C.5 (and v.v.). There is a current tracker issue 
to add the few links that are missing from C.2 to C.5.

-- 
Terry Jan Reedy