[issue16927] Separate built-in types from functions and group similar functions in functions.rst

[Raymond Hettinger]

Raymond Hettinger added the comment:

> This include two main groups that should be separated in 
> two different sections:  built-in types and functions.

I forgot to mention that the docs have already been organized to cover the two groups.  Section 3.2 has the built-in functions and Section 3.4 has the built-in types.  Where they overlap (str and list, for example), section section addresses their use as a function (i.e. list(iterable) acts like a function that loops over an iterable to create a list, and str(x) like a function to lookup the string representation of an object).

The current organization has been somewhat successful and I don't want to damage it by regrouping.  

> This will make it easier to find similar functions,

This isn't the primary role of a library reference.  That said, I would not object to either 1) an extra section that shows a high level grouping of functions or 2) adding to each function a list of see also links (the Microsoft Excel documentation takes that approach).

> and will allow us to factor out some documentation that is repeated[0].

This should not be done either.  For example, we really to want min() and max() to be completely documented in isolation from one another (this is a reference document, repeating definitions as dictionaries do is proper).

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue16927>
_______________________________________