Convention for documenting properties and setters

[leezu]

Sphinx doc does automatically document that an attribute is implemented as a property and if a setter is present.

https://github.com/dmlc/gluon-nlp/pull/429#issuecomment-441460242

[leezu]

@szha Sphinx ignores docstrings on property setters so all documentation for a property must be on the @property method. However, the current documentation does not specify that setting the unknown_lookup is not allowed, so it is actually correct (and the previous behavior was not documented).

We should decide on a consistent way to document properties and their setters. TokenEmbedding but also Vocab contain properties. We may adopt a convention like

@property
def name(self):
    """
    The unique name of the direction.

    :getter: Returns this direction's name
    :setter: Sets this direction's name
    :type: string
    """
    return self._name

https://stackoverflow.com/a/17522081/2560672

[szha]

How does numpy do it?

[leezu]

I don't think numpy uses properties and setters in the user-facing API. A grep yields just a few hits to internals.