[issue33014] Clarify str.isidentifier docstring; fix keyword.iskeyword docstring

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

Separate PRs for doc and code changes will be needed anyway if the code change is restricted to 3.8.

To me, changing keyword.iskeyword.__doc__ from the irrelevant Python tautology 'x.__contains__(y) <==> y in x.' to something that says what the function does, as docstrings should,  is a bug fix, not an enhancement.  Hence a slight slowdown is not a concern to me.  I see 4 possible types of fixes.

1. Write a python function with docstring.  3.8 only as it changes type(iskeyword).

def iskeyword(s):
    "Return true if s is a Python keyword."
    return s in kwlist

2. Change the aberrant set/frozenset.__contains__.__doc__ so it makes some sense as a docstring for a bound method (as with list and dict).  
  list/tuple.__contains__.__doc__ is 'Return key in self.'
  dict.__contains__.__doc__ is 'True if the dictionary has the specified key, else False.'

I would copy the dict __contains__ docstring, with 'Return' prefixed, to set and frozenset, with the obvious substitution.  I don't know about backporting this.

3. Make bound_method docstrings writable, like with Python function docstrings (3.8 only).  Then we could use Cheryl's suggestion.  Or add a function bounddoc(bound_method, docstring) that can change a bound_method's docsting.

CPython uses 2 types for built-in methods bound to an instance.  The choice is not consistent within a class or across classes for a particular method.
  builtin_function_or_method ([].append, frozenset().__contains__)
  method-wrapper ([].__contains__)
Python classes result in 'bound method'.  All 3 copy the docstring of the instance method.  (For Python classes, one can temporarily change the method docstring before creating a new bound method.)

4. Add makebound(method, instance, docstring) that creates a bound method (of the appropriate type) but with the passed docstring (3.8 only)

3 or 4 would allow any public bound method to have a custom docstring.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue33014>
_______________________________________