#3469 closed (fixed)
Django.utils is not documented
| Reported by: | Chris Beaven | Owned by: | Joshua Russo |
|---|---|---|---|
| Component: | Documentation | Version: | dev |
| Severity: | Keywords: | ||
| Cc: | Triage Stage: | Ready for checkin | |
| Has patch: | yes | Needs documentation: | no |
| Needs tests: | no | Patch needs improvement: | yes |
| Easy pickings: | no | UI/UX: | no |
Description (last modified by )
There are a lot of useful utilities and datastructures in django.utils, but the lack of good user documentation limits the extent to which these utilities are used.
For example, DotExpandedDict is a useful but undocumented data structure. It can be very helpful for complex form parsing and it'd be good to mention somewhere in documentation.
Attachments (3)
Change History (17)
comment:1 by , 18 years ago
| Needs documentation: | set |
|---|
comment:2 by , 18 years ago
| Triage Stage: | Unreviewed → Design decision needed |
|---|
comment:3 by , 17 years ago
I think this one in particular needs documentation as it's very useful to a typical end user. I know that I had to ask in the IRC channel to find it originally.
comment:4 by , 17 years ago
| Triage Stage: | Design decision needed → Someday/Maybe |
|---|
Eventually, yes, the general-purpose datastructures in django.utils ought to get documentation.
comment:5 by , 16 years ago
| Description: | modified (diff) |
|---|---|
| Summary: | DotExpandedDict is not documented → Django.utils is not documented |
comment:6 by , 16 years ago
A note to whomever works on this: remember that large portions of django.utils are not considered to be public API, since. Django is a web framework, not a colleation general purpose data structure utilities (we just happen to use some general purpose utilities internally). So we don't guarantee API stability or even future availability and any docs should reflect that. The api-stability document describes where the dividing line lies.
comment:7 by , 15 years ago
| Owner: | changed from to |
|---|
comment:8 by , 15 years ago
| Owner: | changed from to |
|---|
comment:9 by , 15 years ago
| Owner: | changed from to |
|---|---|
| Status: | new → assigned |
comment:10 by , 15 years ago
| Has patch: | set |
|---|---|
| Needs documentation: | unset |
| Patch needs improvement: | set |
Ok, I consider this to be a first pass. It's pretty much all copy-n-paste out of comments and for SortedDict the Wiki. I did try to be relatively smart about it, paying attention to the all lists where appropriate and not including other unnecessary clutter. With that said, this should be very complete but should probably have someone who is not me to review.
by , 15 years ago
| Attachment: | django_utils_ref.diff added |
|---|
Documented django.utils modules listed within API stability section
by , 15 years ago
Rupe's patch with some reST fixes and tweaks. Great work!
comment:12 by , 15 years ago
| Triage Stage: | Someday/Maybe → Ready for checkin |
|---|
Amazing work by Rupe, marking as RFC
comment:13 by , 15 years ago
| Resolution: | → fixed |
|---|---|
| Status: | assigned → closed |
@core: Do we want to document the various classes and functions in django.utils?