Opened 4 years ago

Closed 3 years ago

Last modified 3 years ago

#15338 closed Bug (fixed)

django.utils.decorators isn't documented

Reported by: gabrielhurley Owned by: gabrielhurley
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 timo 3 years ago.
15338.2.diff (1.5 KB) - added by timo 3 years ago.

Download all attachments as: .zip

Change History (13)

comment:1 Changed 4 years ago by russellm

  • Triage Stage changed from Unreviewed to Accepted

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 4 years ago by gabrielhurley

  • Version changed from 1.2 to SVN

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 4 years ago by lrekucki

  • Severity set to Normal
  • Type set to Bug

comment:4 Changed 3 years ago by aaugustin

  • UI/UX unset

Change UI/UX from NULL to False.

comment:5 Changed 3 years ago by aaugustin

  • Easy pickings unset

Change Easy pickings from NULL to False.

Changed 3 years ago by timo

comment:6 Changed 3 years ago by timo

  • 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 3 years ago by ptone

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 3 years ago by timo

comment:8 Changed 3 years ago by timo

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 3 years ago by melinath

  • Triage Stage changed from Accepted to Ready 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 3 years ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from new to closed

In d0345b71146ecb60af2277585b604fbc244d267b:

Fixed #15338 - Documented django.utils.decorators

comment:11 Changed 3 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