This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Improve of abc.py docstring
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eamanu, methane, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2018-12-29 03:05 by eamanu, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
0001-improve-abc.py-docstring.patch eamanu, 2018-12-29 03:05
Pull Requests
URL Status Linked Edit
PR 11352 closed eamanu, 2018-12-29 03:15
PR 11352 closed eamanu, 2018-12-29 03:15
PR 11352 closed eamanu, 2018-12-29 03:15
PR 11355 merged serhiy.storchaka, 2018-12-29 15:28
PR 11355 merged serhiy.storchaka, 2018-12-29 15:28
PR 11355 merged serhiy.storchaka, 2018-12-29 15:28
Messages (8)
msg332693 - (view) Author: Emmanuel Arias (eamanu) * Date: 2018-12-29 03:05
Hi!

I prepare a little improve. I added some samples usage, some clarification and delete some whitespace unnecessary.

Attach patch. 

Regards
msg332705 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-12-29 07:56
Double spaces between sentences increase readability. This is not a bug.

Since abstractclassmethod and like are deprecated and should not be used in new code, I do not see a value of extending their docstrings. Too verbose docstrings make using the module help less convenient. I would rather remove existing examples from docstrings. The module documentation contains more modern examples.
msg332717 - (view) Author: Emmanuel Arias (eamanu) * Date: 2018-12-29 13:50
> Double spaces between sentences increase readability. This is not a bug.

hmm ok. I can see other docstring with not double spaces. But I will ignore. 

> Since abstractclassmethod and like are deprecated and should not be used in new code, I do not see a value of extending their docstrings. 

Ok, you are right. 

> Too verbose docstrings make using the module help less convenient. I would rather remove existing examples from docstrings. The module documentation contains more modern examples.

Do you say that is convenient remove the examples? I can do it! But in defense of the examples on docstring I think those are good, because the are the most quickly reference when coding and those are use by IDE.
msg332718 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-12-29 14:39
These examples teach you how to use abstractclassmethod and similar decorators. But first, docstrings are not tutorial, and second, you should not use them in new code at all, because they are deprecated.
msg332806 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-12-31 07:56
New changeset 5c117dd227e1b4c4f0a62564d8592f1ba45c91eb by Serhiy Storchaka in branch 'master':
bpo-35609: Remove examples for deprecated decorators in the abc module. (GH-11355)
https://github.com/python/cpython/commit/5c117dd227e1b4c4f0a62564d8592f1ba45c91eb
msg332884 - (view) Author: Emmanuel Arias (eamanu) * Date: 2019-01-02 16:47
Hi Serhiy, 

A little question. Is there a planned version to remove the deprecated?
msg332906 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2019-01-03 03:28
No plan for removal.  See https://bugs.python.org/issue28886#msg282582
msg332974 - (view) Author: Emmanuel Arias (eamanu) * Date: 2019-01-04 13:00
> No plan for removal.  See https://bugs.python.org/issue28886#msg282582

Thanks!
History
Date User Action Args
2022-04-11 14:59:09adminsetgithub: 79790
2019-01-04 13:00:08eamanusetmessages: + msg332974
2019-01-03 03:28:24methanesetnosy: + methane
messages: + msg332906
2019-01-02 16:47:04eamanusetmessages: + msg332884
2018-12-31 08:26:03serhiy.storchakasetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2018-12-31 07:56:23serhiy.storchakasetmessages: + msg332806
2018-12-29 15:28:33serhiy.storchakasetpull_requests: + pull_request10666
2018-12-29 15:28:26serhiy.storchakasetpull_requests: + pull_request10665
2018-12-29 15:28:18serhiy.storchakasetpull_requests: + pull_request10664
2018-12-29 14:39:56serhiy.storchakasetmessages: + msg332718
2018-12-29 13:50:58eamanusetmessages: + msg332717
2018-12-29 07:56:39serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg332705
2018-12-29 03:16:02eamanusetstage: patch review
pull_requests: + pull_request10655
2018-12-29 03:15:56eamanusetstage: (no value)
pull_requests: + pull_request10654
2018-12-29 03:15:50eamanusetstage: (no value)
pull_requests: + pull_request10653
2018-12-29 03:05:51eamanucreate