dynamic loading of an instance should prioritize a statically written docstring (if it exists)

[machow]

Generally, dynamic loading works well for modules, classes and functions, but can behave surprisingly for instances. This is because what it means to document an instance is ambiguous.

Consider below:

# Functions ----

def some_func():
    """I am a docstring"""

some_dynamic_func = some_func

some_other_dynamic_func = some_func
"""I am a function"""



# Instances ----

some_int = 1

some_other_int = 2
"""Another int"""

Note that dynamically loading produces these behaviors:

• functions: when documenting any of the functions above (some_func, some_dynamic_fun, some_other_dynamic_func) the docstring some_func.__doc__ is used.
• instances: when documenting some_int or some_other_int, the underlying docstring int.__doc__ is also used.
  • However, this can feel surprising and wrong, because the user took the time to use the special docstring format on some_other_int.

For cases where a variable has a docstring defined below it, we should favor that docstring, so it matches what happens statically.

[machow]

from #307

[has2k1]

What the "official" (PEP 257) sources say about documenting attributes.

String literals occurring elsewhere in Python code may also act as documentation. They are not recognized by the Python bytecode compiler and are not accessible as runtime object attributes (i.e. not assigned to doc), but two types of extra docstrings may be extracted by software tools:

String literals occurring immediately after a simple assignment at the top level of a module, class, or init method are called “attribute docstrings”.
String literals occurring immediately after another docstring are called “additional docstrings”.

What sphinx accepts as documenting attributes

For module data members and class attributes, documentation can either be put into a comment with special formatting (using a #: to start the comment instead of just #), or in a docstring after the definition. Comments need to be either on a line of their own before the definition, or immediately after the assignment on the same line. The latter form is restricted to one line only.

This means that in the following class definition, all attributes can be autodocumented:

class Foo:
    """Docstring for class Foo."""

    #: Doc comment for class attribute Foo.bar.
    #: It can have multiple lines.
    bar = 1

    flox = 1.5   #: Doc comment for Foo.flox. One line only.

    baz = 2
    """Docstring for class attribute Foo.baz."""

    def __init__(self):
        #: Doc comment for instance attribute qux.
        self.qux = 3

        self.spam = 4
        """Docstring for instance attribute spam."""

My takeaway is all """ strings that follow any type of attribute should be recognised as documenting the attribute as there isn't any other competing intent.