Opened 15 months ago

Closed 15 months ago

Last modified 15 months 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: master
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 Changed 15 months ago by edsouza@…

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

comment:2 Changed 15 months ago by timo

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

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 Changed 15 months ago by timo

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

comment:4 Changed 15 months ago by Baptiste Mispelon <bmispelon@…>

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 Changed 15 months ago by Baptiste Mispelon <bmispelon@…>

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 Changed 15 months ago by Baptiste Mispelon <bmispelon@…>

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