Do you feel bad because of the Python docs?

[Terry Reedy]

On 2/26/2013 1:52 PM, Devin Jeanpierre wrote:

> I would assert it isn't very kind to those even with basic fundamentals.
>
> For example, under precisely what circumstances does int() raise
> TypeError? You won't find that under either int's documentation, or
> TypeError's documentation, you have to look it up under __int__, which
> is _not_ a basic fundamental. And rather than helping you along the
> way, the documentation for int() actively misleads you by its
> implicature that the only acceptable types are strings, ints, and
> floats. And then even if you have the foresight to remember "oh yeah,
> isn't there a special method for this?", you have to find the
> documentation for __int__, which is itself is three quarters of the
> way down this massive page:
> http://docs.python.org/2/reference/datamodel.html

Have you opened an issue, or checked for existing issue? I would be open 
to the idea that entries like that for int should not be overly type 
specific and imply that the defaults are the only possibilities.
Perhaps there should be a cross-reference to corresponding special 
methods. Perhaps that idea might be opposed. I am not sure. Perhaps 
Built-in Functions needs a bit more general explanatory text at the top.

-- 
Terry Jan Reedy