[Django] #27656: Fix comment style according to PEP
Django
------------------------------------------------+------------------------
Reporter: Anton Samarchyan | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Uncategorized | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 0 |
------------------------------------------------+------------------------
https://www.python.org/dev/peps/pep-0257/
The docstring is a phrase ending in a period. It prescribes the function
or method's effect as a command ("Do this", "Return that"), not as a
description; e.g. don't write "Returns the pathname ...".
It's also mentioned in the django code style.
Example from test/client.py - docstrings from two different functions.
{{{
"""
Send a TRACE request to the server.
"""
"""
Sets the Factory to appear as if it has successfully logged into a site.
"""
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27656>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
--------------------------------------+------------------------------------
Reporter: Anton Samarchyan | Owner: nobody
Type: Cleanup/optimization | Status: new
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Tim Graham):
* component: Uncategorized => Core (Other)
* stage: Unreviewed => Accepted
Comment:
I think it makes sense to do this rather than to continue explaining to
new contributors about the preferred style (the "bad" style is often
copied from existing code). Whoever works on this, please start small and
send a work-in-progress pull request to make sure you're on the right
track.
--
Ticket URL: <https://code.djangoproject.com/ticket/27656#comment:1>
Django
Reporter: Anton Samarchyan | Owner: Anton
Type: | Samarchyan
Cleanup/optimization | Status: assigned
Component: Core (Other) | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Anton Samarchyan):
* owner: nobody => Anton Samarchyan
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/27656#comment:2>
Django
-------------------------------------+-------------------------------------
Reporter: Anton Samarchyan | Owner: Anton
Type: | Samarchyan
Cleanup/optimization | Status: assigned
Component: Core (Other) | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Anton Samarchyan):
Here's a [https://github.com/django/django/pull/7763 PR] with work in
progress. Made changes to one file.
--
Ticket URL: <https://code.djangoproject.com/ticket/27656#comment:3>
Django
-------------------------------------+-------------------------------------
Reporter: Anton Samarchyan | Owner: Anton
Type: | Samarchyan
Cleanup/optimization | Status: assigned
Component: Core (Other) | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Anton Samarchyan):
* has_patch: 0 => 1
Comment:
I completed all of the changes.
--
Ticket URL: <https://code.djangoproject.com/ticket/27656#comment:4>
Django
-------------------------------------+-------------------------------------
Reporter: Anton Samarchyan | Owner: Anton
Type: | Samarchyan
Cleanup/optimization | Status: assigned
Component: Core (Other) | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"5411821e3b8d1427ee63a5914aed1088c04cc1ed" 5411821e]:
{{{
#!CommitTicketReference repository=""
revision="5411821e3b8d1427ee63a5914aed1088c04cc1ed"
Refs #27656 -- Updated django.contrib docstring verb style according to
PEP 257.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27656#comment:5>
Django
-------------------------------------+-------------------------------------
Reporter: Anton Samarchyan | Owner: Anton
Type: | Samarchyan
Cleanup/optimization | Status: assigned
Component: Core (Other) | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
Changes (by Tim Graham):
* needs_better_patch: 0 => 1
Comment:
A more careful review is required. I found many incomplete changes in the
first commit.
--
Ticket URL: <https://code.djangoproject.com/ticket/27656#comment:6>
Django
-------------------------------------+-------------------------------------
Reporter: Anton Samarchyan | Owner: Anton
Type: | Samarchyan
Cleanup/optimization | Status: assigned
Component: Core (Other) | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"9718fa2e8abe430c3526a9278dd976443d4ae3c6" 9718fa2e]:
{{{
#!CommitTicketReference repository=""
revision="9718fa2e8abe430c3526a9278dd976443d4ae3c6"
Refs #27656 -- Updated django.utils docstring verbs according to PEP 257.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27656#comment:7>
Django
-------------------------------------+-------------------------------------
Reporter: Anton Samarchyan | Owner: Anton
Type: | Samarchyan
Cleanup/optimization | Status: assigned
Component: Core (Other) | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"4696078832f486ba63f0783a0795294b3d80d862" 46960788]:
{{{
#!CommitTicketReference repository=""
revision="4696078832f486ba63f0783a0795294b3d80d862"
Refs #27656 -- Updated django.template/tag docstring verbs according to
PEP 257.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27656#comment:8>
Django
-------------------------------------+-------------------------------------
Reporter: Anton Samarchyan | Owner: Anton
Type: | Samarchyan
Cleanup/optimization | Status: assigned
Component: Core (Other) | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"3eb679a86956d9eedf24492f0002de002f7180f5" 3eb679a]:
{{{
#!CommitTicketReference repository=""
revision="3eb679a86956d9eedf24492f0002de002f7180f5"
Refs #27656 -- Updated django.forms/http docstring verbs according to PEP
257.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27656#comment:9>
Django
-------------------------------------+-------------------------------------
Reporter: Anton Samarchyan | Owner: Anton
Type: | Samarchyan
Cleanup/optimization | Status: assigned
Component: Core (Other) | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"5a6f70b4281817656db2f36c5919036d38fcce7f" 5a6f70b4]:
{{{
#!CommitTicketReference repository=""
revision="5a6f70b4281817656db2f36c5919036d38fcce7f"
Refs #27656 -- Updated django.core docstring verbs according to PEP 257.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27656#comment:10>
Django
-------------------------------------+-------------------------------------
Reporter: Anton Samarchyan | Owner: Anton
Type: | Samarchyan
Cleanup/optimization | Status: assigned
Component: Core (Other) | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"60e52a047e55bc4cd5a93a8bd4d07baed27e9a22" 60e52a0]:
{{{
#!CommitTicketReference repository=""
revision="60e52a047e55bc4cd5a93a8bd4d07baed27e9a22"
Refs #27656 -- Updated django.db docstring verbs according to PEP 257.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27656#comment:11>
Django
-------------------------------------+-------------------------------------
Reporter: Anton Samarchyan | Owner: Anton
Type: | Samarchyan
Cleanup/optimization | Status: assigned
Component: Core (Other) | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"711123e1cdaf3b08c876c045d8d38decdc7a63d3" 711123e1]:
{{{
#!CommitTicketReference repository=""
revision="711123e1cdaf3b08c876c045d8d38decdc7a63d3"
Refs #27656 -- Updated django.views docstring verbs according to PEP 257.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27656#comment:12>
Django
-------------------------------------+-------------------------------------
Reporter: Anton Samarchyan | Owner: Anton
Type: | Samarchyan
Cleanup/optimization | Status: assigned
Component: Core (Other) | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"86de930f413e0ad902e11d78ac988e6743202ea6" 86de930]:
{{{
#!CommitTicketReference repository=""
revision="86de930f413e0ad902e11d78ac988e6743202ea6"
Refs #27656 -- Updated remaining docstring verbs according to PEP 257.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27656#comment:13>
Django
-------------------------------------+-------------------------------------
Reporter: Anton Samarchyan | Owner: Anton
Type: | Samarchyan
Component: Core (Other) | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
Changes (by Tim Graham):
* status: assigned => closed
* resolution: => fixed
--
Ticket URL: <https://code.djangoproject.com/ticket/27656#comment:14>
Django
-------------------------------------+-------------------------------------
Reporter: Anton Samarchyan | Owner: Anton
Type: | Samarchyan
Cleanup/optimization | Status: closed
Component: Core (Other) | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"ba76c3c45b9fee43c2791247e752959781368773" ba76c3c]:
{{{
#!CommitTicketReference repository=""
revision="ba76c3c45b9fee43c2791247e752959781368773"
Refs #27656 -- Removed "This will" prefix from djanog/templatetags/i18n.py
docstrings.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27656#comment:15>