Improve `@property` documentation

[leandro-lucarella-frequenz]

What's needed?

Right now we are documenting properties as if they were functions (a description and a Return section are both required), but they are clearly not.

Google style says properties should be documented as attributes (in the class documentation) but darglint doesn't support this.

Proposed solution

• Properties:

  • @properties are rendered as function (with a special mark for being a property), but this is planned to be improved in the future to be shown as attributes (see Use MkDocs to build the documentation frequenz-channels-python#25 (comment)).

  • Removing documentation from the function and using Attributes: instead somewhat works, but you only get a table in the Class documentation, attributes are not shown in the right ToC, which makes them hard to discover IMHO.

  • The best approach to @properties, that works well with pydocstyle and darglint seems to be the following:

    class AClass:
        """A class."""
    
        @property
        def a_prop(self) -> int:
            """Get the a prop.
    
            Returns:
                The a prop of the class.
            """
            return 1
    
        @a_prop.setter
        def a_prop(self, a: int) -> None:
            pass

    

    The only downside is properties are still listed as functions, not attributes (but this will change, so all good with this), and there is redundancy in the documentation (basically we need to document it twice, one for the description and one for the Returns:. mkdocstrings doesn't show the type if Returns: is not specified, and if the description is not included, pydocstyle complains.

So far the only option seems to be fixing the issue in the upstream darglint tool.

Use cases

No response

Alternatives and workarounds

We tried to use # noqa as suggested in the darglint issue but according to @jakub-toptal it doesn't work:

Before:

@property
def microgrid_api_client(self) -> MicrogridApiClient:
    """Get MicrogridApiClient.

    Returns:
        api client
    """
    return self._api

After:

    @property  # noqa
    def microgrid_api_client(self) -> MicrogridApiClient:  # noqa
        """Get MicrogridApiClient."""  # noqa
        return self._api  # noqa

Still fails with darglint code: DAR201

Additional context

There is a darglint issue for this, and at some point we might want to give it a shot to improve property handling in darglint:

• Handling properties terrencepreilly/darglint#94

[leandro-lucarella-frequenz]

We will generate the documentation with mkdocstrings, which also doesn't support properties super gracefully. It doesn't work well with Attributes: either.

To produce a decent result, the minimum documentation needed is:

class AClass:
    """A class."""

    @property
    def a_prop(self) -> int:
        """
        Returns:
            The a prop of the class.
        """
        return 1

    @a_prop.setter
    def a_prop(self, a: int) -> None:
        pass

(note the Returns: can be next to the """, otherwise it doesn't work either, and if the Returns: is not included, then the type of the property is not included either)

It produces this results:

(so it's not ideal that it is listed as a function, but it is nicely annotated as a writable property)

But pydocstyle complains about this:

in private method `a_prop`:
        D205: 1 blank line required between summary line and description (found 0)
in private method `a_prop`:
        D400: First line should end with a period (not ':')
in private method `a_prop`:
        D401: First line should be in imperative mood (perhaps 'Return', not 'Returns')

So it basically demands a text besides the Returns: section. darglint doesn't complain with this.

So we can explore if we could disable those pydocstyle somehow, or just live with the redundancy of having the properties documented twice. This passes all tests:

class AClass:
    """A class."""

    @property
    def a_prop(self) -> int:
        """Get the a prop.

        Returns:
            The a prop of the class.
        """
        return 1

    @a_prop.setter
    def a_prop(self, a: int) -> None:
        pass

[leandro-lucarella-frequenz]

Given the amount of work that could be involved in making sure all the tools we use work well with one particular way to documenting properties, I'm starting to lean more towards to just drop this issue and bite the bullet.

[leandro-lucarella-frequenz]

Adding the proposed solution to the issue body.