__init__ docstring appears in class documentation

[janscience]

Expected Behavior

Since by default pdoc3 ignores __init__(self) functions of classes, a docstring of an __init__(self) function should not appear anywhere in the generated documentation.

Actual Behavior

The whole docstring of the __init__(self) function is appended (nicely formatted) to the documentation of the class.

Steps to Reproduce

class TestDoc:
    """Test the docs.
    """

    def __init__(self, a):
        """Init the class.

        Some more info that is NOT supposed to show up in the documentation of the `TestDoc` class.
        """
        self.a = a

Additional info

• pdoc version: 0.9.1

[kernc]

I'll disagree. While __init__ isn't documented individually, the constructor is an integral part of any class documentation. It was decided in #24 to pass __init__ params for its class params and to merge the two __doc__ values like Sphinx does.

How would you justify the contrary?

[janscience]

Ok, thank you, that makes sense. So a meaningful way to use the __init__() would be

class TestDoc:
    """Test the docs.
    """

    def __init__(self, a):
        """
        Parameters
        ----------
        a: float
            A number for init
        """
        self.a = a

It would be good know that it behaves this way. I am using pdoc3 because I do not want to use sphinxs...

How about adding this information to the documentation?

[kernc]

The class docstring describes the class. The methods docstrings describe the methods. Whether you place the explicit parameters documentation in the class docstring or in the __init__ docstring is up to you. They are usually listed sequentially (cf. Sphinx, IPython):

# IPython prompt
>>> class C: 
...     """class docstring""" 
...     def __init__(self, a): 
...         """init docstring"""                                                         

>>> C??                                                                                    
Init signature: C(a)
Docstring:      class docstring 
Init docstring: init docstring 
File:           ~/bin/ipython
Type:           type
Subclasses:

How else would you use __init__ and how else could it behave?

[kernc]

FWIW, this changeset makes sense. One always initialized the relevant object with __init__. 👍

[janscience]

Thank you for digging in my code and encouraging me to remove the __init__() docstrings altogether!

Everything you said makes a lot of sense. The only problem is, if all you know is that you should document every function, then you also document the __init__() function. You do not know about the special role of the __init__() docstring. At least that was my mind set. So adding a single line to your documentation in
https://github.com/pdoc3/pdoc/blob/master/pdoc/documentation.md
would clarify this. If you agree I could make a suggestion.

[kernc]

I guess I'd have to see the line first. If you think you can improve the docs, sure, go for it. 👍

[janscience]

Ok, challenge taken. Since it is such a small change I do not make a pull request.

In line 106 of pdoc/documentation.md

pdoc/pdoc/documentation.md

Lines 104 to 107 in 39a1e73

	In the default HTML template, such inherited docstrings are greyed out.
	### Docstrings for variables

I suggest to insert

### Docstrings of `__init__()` methods
[docstrings init methods]: #docstrings-init-methods

Note that the docstring of a class's `__init__()` method is directly appended to the class's docstring when generating the documentation with `pdoc`. A valid approach is to not document the `__init__()` method and directly add, for example, a `Parameters` section to the docstring of the class that describes the arguments of the `__init__()` method. That way all necessary information on how to instantiate the class is provided by the  docstring of the class.

Sorry, it is more than a line... maybe "A valid approach ..." is too much and can be removed.

[janscience]

Ok, I made a pull request #261