search

sphinx-contrib / napoleon

Other
149 stars 48 forks source link

Section for property/descriptor documentation #22

Open McSinyx opened 4 years ago

McSinyx commented 4 years ago

As raised in our project McSinyx/palace#64, there is not yet any canonical way too document descriptors properly. A case in point is

setter = lambda fset: property(fset=fset, doc=fset.__doc__)

@setter
def auxiliary_send(self, value: Tuple[AuxiliaryEffectSlot, int]) -> None:
    """Connect the effect slot to the given send path.

    Any filter properties on the send path remain as they were.
    """
    self.impl.set_auxiliary_send(
        (<AuxiliaryEffectSlot> value[0]).impl, value[1])

Currently we use Parameters which is not exactly intuitive to the readers. Furthermore, the type of the property is not annotated in the rendered document.