Opened 17 years ago

Closed 17 years ago

#3540 closed (fixed)

permalink documentation is incomplete and contains errors

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

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 17 years ago.

Download all attachments as: .zip

Change History (7)

comment:1 by Chris Beaven, 17 years ago

Needs documentation: set
Triage Stage: UnreviewedAccepted

by Chris Beaven, 17 years ago

Attachment: permalink_docs.patch added

comment:2 by Chris Beaven, 17 years ago

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 by James Bennett, 17 years ago

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

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 by David Larlet <larlet@…>, 17 years ago

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

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