Opened 11 years ago

Closed 11 years ago

Last modified 11 years ago

#21855 closed Cleanup/optimization (wontfix)

method prototypes in docs should have self as first argument.

Reported by: anonymous Owned by: nobody
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

For example, the has_perm and has_module_perms prototypes here:
https://github.com/django/django/blob/6f06c749b73abea84cd61a7bcfd1cc9732fbefe5/docs/topics/auth/customizing.txt#L739

Should say:
has_perm(self, perm, obj=None):
...
has_module_perms(self, app_label):

I guess it's implied by the fact they they are methods, but it would be clearer to just include the self argument.

Change History (6)

comment:1 by edsouza@…, 11 years ago

comment:2 by Tim Graham, 11 years ago

Resolution: wontfix
Status: newclosed

Thanks for the suggestion, but it's a common convention not to include them (even the official Python docs do not do so).

comment:3 by Tim Graham, 11 years ago

p.s. Here's the sphinx recommendation not to include the self parameter.

comment:4 by Baptiste Mispelon <bmispelon@…>, 11 years ago

In 79e1d6ebd70898d514a44b85648e3d24104c4243:

Don't show self in the list of arguments of a method.

This is consistent with Python's official documentation
and it's a sphinx recommendation too[1].

[1] http://sphinx-doc.org/markup/desc.html#dir-method

Refs #21855.

comment:5 by Baptiste Mispelon <bmispelon@…>, 11 years ago

In 6bca149af5b8e2d6fb6fe19bdb53904f07248033:

[1.6.x] Don't show self in the list of arguments of a method.

This is consistent with Python's official documentation
and it's a sphinx recommendation too[1].

[1] http://sphinx-doc.org/markup/desc.html#dir-method

Refs #21855.

Backport of 79e1d6ebd70898d514a44b85648e3d24104c4243 from master.

comment:6 by Baptiste Mispelon <bmispelon@…>, 11 years ago

In 126af8fa7bbb711775c3859786955ccb8f3946fb:

[1.5.x] Don't show self in the list of arguments of a method.

This is consistent with Python's official documentation
and it's a sphinx recommendation too[1].

[1] http://sphinx-doc.org/markup/desc.html#dir-method

Refs #21855.

Backport of 79e1d6ebd70898d514a44b85648e3d24104c4243 from master.

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