Another interesting question this raises is whether type.__setattr__ should be checking for values that have `__set_name__` methods defined and calling those methods automatically.

Unfortunately, I think the answer to that is "If we'd thought of that when writing PEP 487, then sure, but it's too late now, as too many folks will be calling it explicitly, and implicitly calling it a second time will cause other, potentially harder to find problems".

So +1 for updating the cached_property docs specifically to mention this problem

However, I'm also wondering if there's somewhere else we should be mentioning it as a general problem.

Perhaps in the docs for __set_name__ itself, noting it as something that authors of descriptors *using* __set_name__ should mention in their docs, with suggested wording?

Something like:

===
`__set_name__`` is only called implicitly as part of the ``type`` constructor, so it will need to be called explicitly with the appropriate parameters when a descriptor is added to a class after initial creation::

    descr = custom_descriptor()
    cls.attr = descr
    descr.__set_name__(cls, 'attr')
===

(The normal sequence is for the descriptor to already be part of the class namespace before __set_name__ gets called)