Decorators are very simple. I'm not surprised that there's not much documentation about them - there's just not much to say.

    @decorator
    def f(...): ...

is equivalent to:

    def f(...): ...
    f = decorator(f)

That's it.

If you read the docs then you basically would not know about them. My experience mirrors the people upthread. I also found that the Python community is very hostile to the idea that the docs might be insufficient, in that people suggesting this in threads were frequently belittled or it was often suggested that the questant should just learn it like they did, or that it wasn't really all that hard.

I've looked at a lot of Javadocs and Python docs. Python's docs leave a lot more up to the imagination and are generally harder to navigate around.

Compare their ThreadPoolExecutors (Python's being inspired by Java's)

https://docs.python.org/3/library/concurrent.futures.html#co...

https://docs.oracle.com/javase/7/docs/api/java/util/concurre...