Opened 8 years ago

Closed 8 years ago

#3540 closed (fixed)

permalink documentation is incomplete and contains errors

Reported by: Thomas Steinacher <tom@…> Owned by: jacob
Component: Documentation Version: master
Severity: Keywords:
Cc: larlet@… Triage Stage: Ready for checkin
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

In the permalink documentation you can find the following example:

def get_absolute_url(self):
    return ('people.views.details', str(self.id))
get_absolute_url = permalink(get_absolute_url)

However, this works only for ids < 10, because the second argument needs to be a tuple or a list. This would be correct:

    return ('people.views.details', (str(self.id),))

Also, the documentation is incomplete. It is not mentioned that permalink accepts named parameters (this is described e.g. on http://collingrady.com/2007/02/15/django-permalink/)

Attachments (1)

permalink_docs.patch (1.1 KB) - added by SmileyChris 8 years ago.

Download all attachments as: .zip

Change History (7)

comment:1 Changed 8 years ago by SmileyChris

  • Needs documentation set
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

Changed 8 years ago by SmileyChris

comment:2 Changed 8 years ago by SmileyChris

  • Needs documentation unset
  • Triage Stage changed from Accepted to Ready for checkin

This is good to update the decorator docs for now.

I also just opened a related ticket #3683 which changes both the behaviour and documentation for the better.

comment:3 Changed 8 years ago by ubernostrum

I'd actually like to see the docs give an example of using keyword args, because it's decidedly non-obvious (took me a couple tries, and some breakage, to figure it out).

comment:4 Changed 8 years ago by mtredinnick

I agree. I'll fix that when I check it in; once Chris and I sort out which one of us is on crack in #3683. I've got the change written, but I want to sort out the other ticket first to avoid embarrassing myself.

comment:5 Changed 8 years ago by David Larlet <larlet@…>

  • Cc larlet@… added

In the same time, can you remove the line 27 of init.py (in permalink function), maybe I'm tired but it seems to be useless(?)

I'm +1 on improving doc for permalink, it's a great new feature. I've discovered this in cheeserater and even if I'm on the devel mailing-list, it could be useful to have a recap of "added features of the week" on the django weblog isn't it?

comment:6 Changed 8 years ago by mtredinnick

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

(In [4879]) Fixed #3540 -- Updated permalink documentation to fix an error and document how
to pass keyword arguments.

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