[Python-Dev] [Python-checkins] cpython: Issue #11223: Add threading._info() function providing informations about the

[exarkun at twistedmatrix.com]

On 01:11 pm, benjamin at python.org wrote:
>2011/4/20  <exarkun at twistedmatrix.com>:
>>On 08:20 am, victor.stinner at haypocalc.com wrote:
>>>
>>>Hi,
>>>
>>>Le mardi 19 avril 2011 à 22:42 -0400, Terry Reedy a écrit :
>>>>
>>>>On 4/19/2011 5:59 PM, victor.stinner wrote:
>>>>
>>>> >    Issue #11223: Add threading._info() function providing 
>>>>informations
>>>> > about the
>>>> > thread implementation.
>>>>
>>>>Since this is being documented, making it part of the public api, 
>>>>why
>>>>does it have a leading underscore?
>>>
>>
>>Can I propose something wildly radical?  Maybe the guarantees made 
>>about
>>whether an API will be available in future versions of Python 
>>(ostensibly
>>what "public" vs "private" is for) should not be tightly coupled to 
>>the
>>decision about whether to bother to explain what an API does?
>
>With what criteria would you propose to replace it with?

I'm not sure what kind of criteria you're thinking of.  I'm only 
suggesting that:

  1) Document whatever you want (preferably as much as possible)

  2) Make "privateness" defined by whether there is a leading underscore

It is a big mistake to think that documentation isn't necessary for 
things just because you don't want application developers to use them. 
Maintainers benefit from it just as much.

Jean-Paul