Page MenuHomePhabricator
Create Task
Maniphest T121366

deprecation decorators should add deprecation information to docstrings
Closed, ResolvedPublic
Actions

Description

T121365 shows many instances where the docstring has 'DEPRECATED' explicitly added to the docstring.

There will be other cases where a method is decorated with @deprecated but the docstring was not updated to mention it is deprecated, or there is no docstring at all.

All the existing literal DEPRECATED in docstrings should be removed, and the deprecated decorator should add/alter the function's docstring to describe the deprecation for documentation.

This task doesnt need to solve T121365; it could simply replicate the existing problem by prefixing the docstrings with 'DEPRECATED:' .
There are alternatives which would pass the new pep257 rule, such as appending (DEPRECATED). to the end of the first line of the docstring.

Details

SubjectRepoBranchLines +/-
Add deprecation notice (if necessary) to docstring of @deprecated functionspywikibot/coremaster+84 -0
[WIP] Remove unnecessary DEPRECATED notices from docstringspywikibot/coremaster+44 -103
Customize query in gerrit

Related Objects
Search...

Event Timeline

jayvdb created this task.Dec 13 2015, 10:15 PM
jayvdb raised the priority of this task from to Needs Triage.
jayvdb updated the task description. (Show Details)
jayvdb added projects: Pywikibot, Pywikibot-Documentation.
jayvdb added subscribers: Aklapper, StudiesWorld, jayvdb, pywikibot-bugs-list.
Restricted Application added a project: Documentation. · View Herald TranscriptDec 13 2015, 10:15 PM
jayvdb added a comment.Dec 13 2015, 10:18 PM

As decorators are fairly 'advanced Python', and are complex to build/modify/test, this would be a good Google-Code-In-2015 project for someone wanting to increase their Python skills.

jayvdb added a project: Google-Code-In-2015.Dec 14 2015, 12:21 PM

https://codein.withgoogle.com/dashboard/tasks/6157348213096448/

jayvdb moved this task from Proposed to Imported into GCI site on the Google-Code-In-2015 board.Dec 14 2015, 12:22 PM
jayvdb added a subscriber: Sn1per.
Nemo_bis mentioned this in T120024: [clonable] Add doctests to Pywikibot library documentation.Jan 9 2016, 10:07 AM
Sn1per claimed this task.Jan 22 2016, 9:25 PM
Sn1per added a comment.Jan 23 2016, 4:02 AM

I imagine a regex could be used to make @deprecate_arg do something similar.

gerritbot subscribed.Jan 23 2016, 4:02 AM

Change 265899 had a related patch set uploaded (by Sn1per):
Add deprecation notice to docstring in @deprecated decorator

https://gerrit.wikimedia.org/r/265899

gerritbot added a project: Patch-For-Review.Jan 23 2016, 4:02 AM
gerritbot added a comment.Jan 23 2016, 4:56 AM

Change 265902 had a related patch set uploaded (by Sn1per):
[WIP]Remove unnecessary DEPRECATED notices from docstrings

https://gerrit.wikimedia.org/r/265902

Xqt subscribed.Jan 23 2016, 7:41 AM

What is wrong keeping "Deprecated" in doc string? Please keep in mind doc strings are comments for human readability to explain a method inside the code. But it would be wrong to have access to those comments via post-processors on an external sheet only.

jayvdb added a comment.Jan 23 2016, 7:57 AM

The @deprecated is also human readable. The 'problem' with adding 'Deprecated' to the docstring is they are not kept in sync with @deprecated. We have so many instances where this hasnt been done; it slips through code review, as we dont have a code style checker for it (and it would be difficult to create one).

But if you want to create a code style checker, that would also be great.

This decorator could check if 'Deprecated.' is in the docstring already, and not add it.

Xqt added a comment.Jan 23 2016, 2:55 PM

@jayvdb any idea how to implement a hook for additional test stuff?

gerritbot added a comment.Jan 24 2016, 6:17 AM

Change 265902 abandoned by Sn1per:
[WIP] Remove unnecessary DEPRECATED notices from docstrings

Reason:
Per T121366#1958826

https://gerrit.wikimedia.org/r/265902

AndyTechGuy subscribed.Jan 30 2016, 1:59 AM
gerritbot added a comment.Jan 30 2016, 9:46 AM

Change 265899 merged by jenkins-bot:
Add deprecation notice (if necessary) to docstring of @deprecated functions

https://gerrit.wikimedia.org/r/265899

Xqt closed this task as Resolved.Jan 30 2016, 7:06 PM
Sn1per mentioned this in T126278: Deprecated argument decorators should add deprecation notices to docstrings.Feb 8 2016, 10:14 PM
Content licensed under Creative Commons Attribution-ShareAlike (CC BY-SA) 4.0 unless otherwise noted; code licensed under GNU General Public License (GPL) 2.0 or later and other open source licenses. By using this site, you agree to the Terms of Use, Privacy Policy, and Code of Conduct. · Wikimedia Foundation · Privacy Policy · Code of Conduct · Terms of Use · Disclaimer · CC-BY-SA · GPL