Question about requiring __init__ docstrings

[marc2982]

I can't seem to find any good examples on the internet concerning meaningful __init__ docstrings. There may be times when there are no parameters, or perhaps documenting the parameters would be helpful.

PEP 257 does say:

Public methods (including the __init__ constructor) should also have docstrings.

but applying this rule seems unnecessary at times.

This is what makes sense to me:

class Klass:

    """Docstring here."""

    def __init__(self, component):
        """

        component - The component to model. Can be a name or something else.

         """
         self.component = component

But of course, pep257 gives this:

PEP257 Short description should end with a period.

This is what I have ended up doing, but it seems awkward and unnecessary just to ensure pep257 does not complain.

Example:

    def __init__(self, component):
        """The constructor.

        component - The component to model. Can be the name of the model or a path to a file.
        """
        self.component = component

I have tried searching online to see how industry treats it, but it seems almost everyone doesn't document the __init__ unless there is a compelling reason to do so. As an example, see the Error class in pep257. :D

class Error(object):

    """Error in docstring style.

    * Stores relevant data about the error,
    * provides format for printing an error,
    * provides __lt__ method to sort errors.

    """

    # options that define how errors are printed
    explain = False
    range = False
    quote = False

    def __init__(self, filename, source, docstring, context,
                 explanation, start=None, end=None):
        self.filename = filename
        self.source = source
        self.docstring = docstring
        self.context = context
        self.explanation = explanation.strip()

So the question is, can/should something be added/changed in pep257 to avoid this? Is this a problem with the specification, the tool, or perhaps neither?

Any insight you guys have would be great.

[keleshev]

Error doesn't have __init__ docstring because Error is not a part of a public interface. This is not explicit right now, but soon pep257 will try to check that in __all__ variable.

In your case I would do:

class Backend:

    """Docstring here."""

    def __init__(self, component):
        """Backend that is based on a `component`."""
        self.component = component

So I don't see any need to change pep257 or PEP 257.

[kantorii]

The following issue is still open at this point in time for this discussion.
#189