Opened 10 years ago

Closed 9 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 Chris Beaven 10 years ago.

Download all attachments as: .zip

Change History (7)

comment:1 Changed 10 years ago by Chris Beaven

Needs documentation: set
Needs tests: unset
Patch needs improvement: unset
Triage Stage: UnreviewedAccepted

Changed 10 years ago by Chris Beaven

Attachment: permalink_docs.patch added

comment:2 Changed 10 years ago by Chris Beaven

Needs documentation: unset
Triage Stage: AcceptedReady 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 10 years ago by James Bennett

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 10 years ago by Malcolm Tredinnick

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 10 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 9 years ago by Malcolm Tredinnick

Resolution: fixed
Status: newclosed

(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