New submission from Serhiy Storchaka <storchaka+cpyt...@gmail.com>:
Difflib docstrings contain short descriptions of functions and methods defined in the module and classes. It is redundant because pydoc shows descriptions for every function and method just few lines below. For example: | Methods: | | __init__(linejunk=None, charjunk=None) | Construct a text differencer, with optional filters. | | compare(a, b) | Compare two sequences of lines; generate the resulting delta. | | Methods defined here: | | __init__(self, linejunk=None, charjunk=None) | Construct a text differencer, with optional filters. | | The two optional keyword parameters are for filter functions: | | - `linejunk`: A function that should accept a single string argument, | and return true iff the string is junk. The module-level function | `IS_LINE_JUNK` may be used to filter out lines without visible | characters, except for at most one splat ('#'). It is recommended | to leave linejunk None; the underlying SequenceMatcher class has | an adaptive notion of "noise" lines that's better than any static | definition the author has ever been able to craft. | | - `charjunk`: A function that should accept a string of length 1. The | module-level function `IS_CHARACTER_JUNK` may be used to filter out | whitespace characters (a blank or tab; **note**: bad idea to include | newline in this!). Use of IS_CHARACTER_JUNK is recommended. | | compare(self, a, b) | Compare two sequences of lines; generate the resulting delta. | | Each sequence must contain individual single-line strings ending with | newlines. Such sequences can be obtained from the `readlines()` method | of file-like objects. The delta generated also consists of newline- | terminated strings, ready to be printed as-is via the writeline() | method of a file-like object. | | Example: It leads to confusion because it looks like methods are described twice. Also the signature of a method in the class docstring can be outdated. For example the description of SequenceMatcher.__init__ was not updated for new parameter autojunk. ---------- assignee: docs@python components: Documentation messages: 401923 nosy: docs@python, serhiy.storchaka priority: normal severity: normal status: open title: Remove redundand information from difflib docstrings type: enhancement versions: Python 3.11 _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue45216> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com