permalink documentation is incomplete and contains errors

[Thomas Steinacher <tom@…>]

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/)

[Chris Beaven]

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.

[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).

[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.

[David Larlet <larlet@…>]

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?

[Malcolm Tredinnick]

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