Opened 6 years ago

Closed 4 years ago

Last modified 4 years ago

#15338 closed Bug (fixed)

django.utils.decorators isn't documented

Reported by: Gabriel Hurley Owned by: Gabriel Hurley
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: timograham@… Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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.

Attachments (2)

15338.diff (753 bytes) - added by Tim Graham 4 years ago.
15338.2.diff (1.5 KB) - added by Tim Graham 4 years ago.

Download all attachments as: .zip

Change History (13)

comment:1 Changed 6 years ago by Russell Keith-Magee

Triage Stage: UnreviewedAccepted

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.

comment:2 Changed 6 years ago by Gabriel Hurley

Version: 1.2SVN

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 ;-)

comment:3 Changed 6 years ago by Łukasz Rekucki

Severity: Normal
Type: Bug

comment:4 Changed 5 years ago by Aymeric Augustin

UI/UX: unset

Change UI/UX from NULL to False.

comment:5 Changed 5 years ago by Aymeric Augustin

Easy pickings: unset

Change Easy pickings from NULL to False.

Changed 4 years ago by Tim Graham

Attachment: 15338.diff added

comment:6 Changed 4 years ago by Tim Graham

Cc: timograham@… added
Has patch: set

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?

comment:7 Changed 4 years ago by 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!

Changed 4 years ago by Tim Graham

Attachment: 15338.2.diff added

comment:8 Changed 4 years ago by 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.

comment:9 Changed 4 years ago by melinath

Triage Stage: AcceptedReady for checkin

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.

comment:10 Changed 4 years ago by Tim Graham <timograham@…>

Resolution: fixed
Status: newclosed

In d0345b71146ecb60af2277585b604fbc244d267b:

Fixed #15338 - Documented django.utils.decorators

comment:11 Changed 4 years ago by Tim Graham <timograham@…>

In cf482d6e2a322a8c84570ae282b774fa09491c98:

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

Backport of d0345b7114 from master

Note: See TracTickets for help on using tickets.
Back to Top