search

tantale / deprecated

Python @deprecated decorator to deprecate old python classes, functions or methods.
MIT License
298 stars 32 forks source link

Sphinxify docstring #45

Closed AstraLuma closed 3 years ago

AstraLuma commented 3 years ago

deprecated.sphinx.deprecated didn't have a very good docstring

tantale commented 3 years ago

Unlike other Sphinx decorators, the @deprecated decorator can be a decorator factory (with parameters) or a basic decorator (without parameter). I have to check if the second scenario (without parameter) makes sense.

tantale commented 3 years ago

The decoration of the following functions is bad.

No parameter at all:

@deprecated
def bad1():
    pass

Missing version argument:

@deprecated(reason="bad reason")
def bad2():
    pass

As a conclusion, I will change the signature of the Sphinx @deprecated decorator to reflect the valid use cases.