spadarian / docblock-python

Atom plugin to insert documentation blocks for python functions
GNU General Public License v2.0
22 stars 9 forks source link

Missing class docstring formats in Google, Numpy styles #3

Closed SKalt closed 6 years ago

SKalt commented 6 years ago

The numpy style guide prescribes something like

class Photo(ndarray):
    """
    Array with associated photographic information.

    ...

    Attributes
    ----------
    height             # has its own docstring
    exposure : float
        Exposure in seconds.

    Methods          # optional, since they have their own docstrings
    -------
    colorspace(c='rgb')
        Represent the photo in the given colorspace.
    gamma(n=1.0)
        Change the photo's gamma exposure.

and the google style guides requires the form

class SampleClass(object):
    """Summary of class here.

    Longer class information....
    Longer class information....

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

This package should be capable of templating these class docstrings.

spadarian commented 6 years ago

I added support for class docstrings. Let me know if you have any problem.

piccolbo commented 6 years ago

This is my test:

class DocblockTest(object):
    """Short summary.

    Parameters
    ----------
    f1 : type
        Description of parameter `f1`.
    f2 : type
        Description of parameter `f2`.

    Attributes
    ----------
    field1 : type
        Description of attribute `field1`.

    """
    field1 = None
    field2 = 1

    def __init__(self, f1, f2):
        self.field1 = f1

    def othermethod(self, arg):
        return self + arg

I don't see a methods section; field 2 was missed among the attributes. This v 0.5.0. Was I supposed to install a dev version? Thanks