[Python-Dev] Convention on functions that shadow existing stdlib functions

[Terry Reedy]

On 7/29/2011 7:27 PM, Antoine Pitrou wrote:
> On Fri, 29 Jul 2011 19:02:32 -0400
> Terry Reedy<tjreedy at udel.edu>  wrote:
>> On 7/29/2011 5:32 PM, Antoine Pitrou wrote:
>>> On Fri, 29 Jul 2011 11:51:18 -0400
>>> Barry Warsaw<barry at python.org>   wrote:

>>>> The solution then is to rename test.support to test._support to make it clear
>>>> it's an internal implementation detail.  Then you can remove the entire
>>>> section from the stdlib docs and just document it in the code.
>>>
>>> Ideally so.
>>
>> The effect of this will be to discourage new people (including myself in
>> the category) from writing or reviewing patches.
>
> I'm sorry, can you be more precise. The effect of what?

Your proposal to remove the current formatted documentation of 
test.support instead of completing it and force all developers to only 
have reference to the docstrings scattered through the code.

> And why would that be so?

Because not everyone is like you. Because the condensed formatted docs 
make learning and using a module significantly easier for some people.

Terry Jan Reedy