[issue35609] Improve of abc.py docstring
New submission from Emmanuel Arias <emmanuelarias30@gmail.com>: Hi! I prepare a little improve. I added some samples usage, some clarification and delete some whitespace unnecessary. Attach patch. Regards ---------- assignee: docs@python components: Documentation files: 0001-improve-abc.py-docstring.patch keywords: patch messages: 332693 nosy: docs@python, eamanu priority: normal severity: normal status: open title: Improve of abc.py docstring type: enhancement versions: Python 3.8 Added file: https://bugs.python.org/file48021/0001-improve-abc.py-docstring.patch _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35609> _______________________________________
Change by Emmanuel Arias <emmanuelarias30@gmail.com>: ---------- pull_requests: +10653 stage: -> patch review _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35609> _______________________________________
Change by Emmanuel Arias <emmanuelarias30@gmail.com>: ---------- pull_requests: +10653, 10654 stage: -> patch review _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35609> _______________________________________
Change by Emmanuel Arias <emmanuelarias30@gmail.com>: ---------- pull_requests: +10653, 10654, 10655 stage: -> patch review _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35609> _______________________________________
Serhiy Storchaka <storchaka+cpython@gmail.com> added the comment: 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. ---------- nosy: +serhiy.storchaka _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35609> _______________________________________
Emmanuel Arias <emmanuelarias30@gmail.com> added the comment:
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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35609> _______________________________________
Serhiy Storchaka <storchaka+cpython@gmail.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35609> _______________________________________
Change by Serhiy Storchaka <storchaka+cpython@gmail.com>: ---------- pull_requests: +10664 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35609> _______________________________________
Change by Serhiy Storchaka <storchaka+cpython@gmail.com>: ---------- pull_requests: +10664, 10665 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35609> _______________________________________
Change by Serhiy Storchaka <storchaka+cpython@gmail.com>: ---------- pull_requests: +10664, 10665, 10666 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35609> _______________________________________
Serhiy Storchaka <storchaka+cpython@gmail.com> added the comment: 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/5c117dd227e1b4c4f0a62564d8592f1ba45... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35609> _______________________________________
Change by Serhiy Storchaka <storchaka+cpython@gmail.com>: ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35609> _______________________________________
Emmanuel Arias <emmanuelarias30@gmail.com> added the comment: Hi Serhiy, A little question. Is there a planned version to remove the deprecated? ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35609> _______________________________________
INADA Naoki <songofacandy@gmail.com> added the comment: No plan for removal. See https://bugs.python.org/issue28886#msg282582 ---------- nosy: +inada.naoki _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35609> _______________________________________
Emmanuel Arias <emmanuelarias30@gmail.com> added the comment:
No plan for removal. See https://bugs.python.org/issue28886#msg282582
Thanks! ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35609> _______________________________________
participants (3)
-
Emmanuel Arias -
INADA Naoki
-
Serhiy Storchaka