Documenting Pythons @property "attributes" with docstrings

Question

I gather that docstrings are more of a personal preference than anything, but I wanted to get the opinion of some people smarter than I ...

Is this a legitimate way to document the get/set nature pythons @property descriptor attributes?

class Handle(rgm.RigModule):
    '''
    Handle nodes are intended to be keyable transforms, made viewable by shape nodes connected as children

    @Properties:

        parent:
            Transform: Returns Transform instance if parent exists, otherwise None
        parent.setter:
            (str): Sets parent transform. (Accepts string name of transform, or any instance of the Transform class)

        shape:
            str: returns string representation of current shape
        shape.setter:
            (str): sets current shape using string representation provided.  If string key does not exist in library, shape will be set to None

        shapeDraw:
            dict: returns dictionary of shape data
        shapeDraw.setter:
            (dict): sets current shapes using data

        shapeColor:
            int: returns integer representation of current shape color
        shapeColor.setter:
            (int): sets current shape color using integer provided.

        shapeColor:
            int: returns integer representation of current shape color
        shapeColor.setter:
            (int): sets current shape color using integer provided.

        shapeTranslate:
            list: returns a 3list of the shape nodes relative offset translation
        shapeTranslate.setter:
            (list): sets relative offset translation of the shape nodes

        shapeRotate:
            list: returns a 3list of the shape nodes relative offset rotation
        shapeRotate.setter:
            (list): sets relative offset rotation of the shape nodes

        shapeScale:
            list: returns a 3list of the shape nodes relative offset scale
        shapeScale.setter:
            (list): sets relative offset scale of the shape nodes

        shapeMatrix:
            list: returns a 8list of the shape nodes relative offset matrix
        shapeMatrix.setter:
            (list): sets relative offset matrix of the shape nodes

Answer 1

Docstring format depend on what IDE or automatic document generation tools you are using. I can give an example for PyCharm IDE because I use it always in my work.

If you are using PyCharm the docstring is a powerful way to enhance IDE analyzer results. You can read a lot about how write "right" docstring for this IDE here. Below some examples:

class Character(object):
    pass


class Item(object):

    def __init__(self, owner=None):
        """
        :type owner: Character or None
        """
        self.__owner = owner

    @property
    def owner(self):
        """:rtype: Animal"""
        return self.__owner

    @owner.setter
    def owner(self, value):
        """:type value: Character"""
        self.__owner = value


class ArmorItem(Item):
    def __init__(self, defence, owner=None):
        """
        :type defence: int
        :type owner: Character or None
        """
        super(ArmorItem, self).__init__(owner)
        self.__defence = defence

    @property
    def defence(self):
        """:rtype: int"""
        return self.__defence


class Shield(ArmorItem):

    def block(self, damage):
        """
        :param int damage: The damage that can hero get
        :rtype: bool
        """
        if self.defence > damage:
            return True
        return False


class Helm(ArmorItem):

    def save(self, damage):
        """
        :param int damage: The damage that can hero get
        :rtype: bool
        """
        if self.defence > damage:
            return True
        return False


class Sword(Item):

    def __init__(self, damage, owner=None):
        """
        :type damage: int
        :type owner: Character or None
        """
        super(Sword, self).__init__(owner)
        self.__damage = damage


class Hero(Character):

    def __init__(self, name, weapon, armors):
        """
        :param str name: Hero name
        :param weapon weapon: Hero weapon
        :param list of ArmorItem armors: The armor item that have hero
        """
        super(Hero, self).__init__()

        self.__name = name
        self.__weapon = weapon

        self.__armors = armors
        for armor in self.__armors:
            armor.owner = self

    @property
    def name(self):
        """:rtype: str"""
        return self.__name

    @property
    def weapon(self):
        """:rtype: Sword"""
        return self.__weapon

    @property
    def armors(self):
        """:rtype: list of ArmorItem"""
        return self.__armors


def main():
    """
    Here method documentation can be placed.
    There is a test function to show analyzer facilities when a good docstring specified.

    Of course where I wrote "error" it mean that not Python exception will be thrown.
    In this place analyzer (e.g. PyCharm) show that it's something wrong.
    """
    weapon_bad1 = Sword(34.2)  # Error because damage is not int
    weapon_bad2 = Sword(20, weapon_bad1)  # Error because owner is not appropriate class

    weapon = Sword(10)  # Ok
    helm = Helm(20)  # Ok
    shield = Shield(30)  # Ok

    # Specify that all_items it not list but it list of Item (any)
    all_items = [weapon, helm, shield]
    """:type: list of Item"""

    hero_bad = Hero("bad", weapon, all_items)  # Again error here because all_items is not ArmorItem list
    hero_good = Hero("good", weapon, [helm, shield])

    # "Cast type" to notify analyzer that we get not ArmorItem but we get concrete ArmorItem
    some_armor = hero_good.armors[0]
    """:type: Helm"""

    some_armor.save(10)  # Ok, Helm class has save method
    some_armor.block(10)  # Error, Helm class has not block method


if __name__ == "__main__":
    main()

And what you can see in IDE if right docstrings specified in each methods:

Note PyCharm IDE analyzer can help very much when docstrings specified (extended list of docstring format you can find in link at the answer beginning).