documentation - How do I document a constructor for a class using Python dataclasses?

Question

I have some existing Python 3.6 code that I'd like to move to Python 3.7 dataclasses. I have __init__ methods with nice docstring documentation, specifying the attributes the constructors take and their types.

However, if I change these classes to use the new Python dataclasses in 3.7, the constructor is implicit. How do I provide constructor documentation in this case? I like the idea of dataclasses, but not if I have to forego clear documentation to use them.

edited to clarify I'm using docstrings presently

Answer 1

The napoleon-style docstrings as they are described in the sphinx docs (see the ExampleError class for their take on it) explicitly touch on your case:

The __init__ method may be documented in either the class level docstring, or as a docstring on the __init__ method itself.

And if you do not want this behavior, you have to explicitly tell sphinx that the constructor docstring and the class docstring are not the same thing.

Meaning, you can just paste your constructor info into the body of the class docstring.

---

In case you build documents from your docstrings, these are the granularities that can be achieved:

1) The bare minimum:

@dataclass
class TestClass:
    """This is a test class for dataclasses.

    This is the body of the docstring description.
    """
    var_int: int
    var_str: str

2) Additional constructor parameter description:

@dataclass
class TestClass:
    """This is a test class for dataclasses.

    This is the body of the docstring description.

    Args:
        var_int (int): An integer.
        var_str (str): A string.

    """
    var_int: int
    var_str: str

3) Additional attribute description:

@dataclass
class TestClass:
    """This is a test class for dataclasses.

    This is the body of the docstring description.

    Attributes:
        var_int (int): An integer.
        var_str (str): A string.

    """
    var_int: int
    var_str: str

---

Parameter and attribute descriptions can of course be combined as well, but since dataclasses should be straight forward mappings I don't see a reason to do so.

In my opinion, 1) would do for small or simple dataclasses -- it already includes the constructor signature with their respective types, which is plenty for a dataclass. If you want to say more about each attribute, 3) would serve best.