django.utils.decorators isn't documented

[Gabriel Hurley]

It's certainly not the only thing that's not documented in django.utils, but there are a few useful decorators there. In particular, method_decorator which is discussed in the CBV docs would be good to document.

[Russell Keith-Magee]

Technically, the reason that it's not documented is because it's ​not officially stable API. However, given that tools like method_decorator are pretty much essential now, we should probably formalize the contents of utils.decorators.

[Gabriel Hurley]

Haha, the fact that it's not officially stable by virtue of *omission* from that list would be why grepping it didn't help.

I didn't mean to imply that everything in it should be documented publicly, but at least a couple of them (as you say) have become de facto public APIs.

My new favorite toy is the -n flag on the sphinx builder which shows warnings for every broken crossref... so I see lots of things that aren't documented now ;-)

[Aymeric Augustin]

Change UI/UX from NULL to False.

[Aymeric Augustin]

Change Easy pickings from NULL to False.

[Tim Graham]

Added a simple patch for method_decorator, would anyone like to weigh in on the usefulness of documenting any of the other functions in decorators?

[Preston Holmes]

I'd think documenting decorator_from_middleware* would be worth it - they have pretty extensive use in the wild, aren't likely to change, and can be pretty valuable if you found middleware you want to use, but only on some views.

Since decorators already take some degree of head warping, I'm not sure the word "dynamically" adds a lot here:

https://code.djangoproject.com/attachment/ticket/15338/15338.diff#L13

Thanks Tim for the dedication to the docs!

[Tim Graham]

Thanks for the feedback. I can't take credit for "dynamically" or most of this patch as it's mostly copied from docstrings.

[Stephen Burrows]

Looks good to me. Patch applies cleanly, docs generate. The other functions don't feel nearly as widely-applicable as the ones that are already documented.

[Tim Graham <timograham@…>]

In d0345b71146ecb60af2277585b604fbc244d267b:

Fixed #15338 - Documented django.utils.decorators

[Tim Graham <timograham@…>]

In cf482d6e2a322a8c84570ae282b774fa09491c98:

[1.4.X] Fixed #15338 - Documented django.utils.decorators

Backport of d0345b7114 from master