[docs] [issue11776] Constructor signatures missing in types module documentation

[Terry J. Reedy]

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

I agree that we should properly document all of the types, even if belately.

A PR is premature until we agree in more detail what 'properly' means.  The most recent patch 'complete-patch...' has multiple errors and needs major revision, to the point that a new patch will be 'based on' rather than 'an edit' of Hoy's work.

1. The table needs to be explained.  It should not just duplicate explanation elsewhere in the doc.  Currently it only lists classes with Python signatures that can be instantiated from Python.  It might make more sense to have a table of types that cannot be instantiated, and not list them elsewhere.

The table seems to be a response to an unreferenced and incomplete (and therefore non-authoritative) suggestion.  We should do what seems best now.

Perhaps there should be two tables for non-callable and callable (from Python) types.  The former without individual entries, the latter with, and with links thereto in the table.

Or perhaps skip tables and just make two subsections for the two groups of types/classes.  There are not currently alphabetical anyway.

2. The types that cannot be instantiated have wrong doc.
"+   This does support direct creation."
This seems to be Nick's
"This type does support direct creation "
However, 'this' referred to ModuleType, not to the 'do not call' type he listed previously.

Correct would be "This type cannot be instantiated by calling it." and I would prefer saying this just once and listing the modules in a table with short explanation.  Table intro might be
"The following types cannot be instantiated by calling them from Python.  Hence no argument signature is given."

3. The wrong initial comments are followed by the wrong 
"Please see :class:`XyzType` (imp.new_module).
Again, these are derived from Nick's comment that only applies to callable ModuleType.

The reference to imp is obsolete as imp is deprecated.  The imp.new_module(name) entry says to use importlib.util.module_from_spec(spec), but a name is not spec.  We don't need to add this; see below.

4. The patch does not touch the ModuleType entry, currently (3.7 online):

 class types.ModuleType(name, doc=None)
    The type of modules. Constructor takes the name of the module to be created and optionally its docstring.

    Note
    Use importlib.util.module_from_spec() to create a new module if you wish to set the various import-controlled attributes.

This looks fine.  The only thing we might change is the awkward 'Constructor takes' to 'A call takes' or something.

----------

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