[Python-Dev] Documentation strategy for PEP 3151

[Terry Reedy]

On 10/12/2011 10:58 AM, Barry Warsaw wrote:
> On Oct 12, 2011, at 10:24 AM, Benjamin Peterson wrote:
>
>> 2011/10/12 Antoine Pitrou<solipsis at pitrou.net>:
>>> I'd like some advice on what the best path is in cases such as:
>>>
>>>    A :exc:`socket.error` is raised for errors from the call
>>>    to :func:`inet_ntop`.
>>>
>>> Should I replace "socket.error" with "OSError" (knowing that the
>>> former is now an alias of the latter), or leave "socket.error" so that
>>> people have less surprises when running their code with a previous
>>> Python version?
>>
>> I think you should say OSError but leave a historical note with a
>> versionchanged on it.
>
> +1

Given that tracebacks for uncaught socket errors will end with OSError, 
the doc should say that is what is raised. The edits and notes I have 
seen so far today look fine.

I also liked the What's New example. The new version looks *much* 
better, and not just because of the deleted import, but because the 
changes allow a much clearer structure that is more pleasant to read. So 
my thanks also for carrying out this project.

-- 
Terry Jan Reedy