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.

Author serhiy.storchaka
Recipients docs@python, serhiy.storchaka
Date 2021-09-16.07:33:29
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1631777610.22.0.0340838668525.issue45216@roundup.psfhosted.org>
In-reply-to
Content
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.
History
Date User Action Args
2021-09-16 07:33:30serhiy.storchakasetrecipients: + serhiy.storchaka, docs@python
2021-09-16 07:33:30serhiy.storchakasetmessageid: <1631777610.22.0.0340838668525.issue45216@roundup.psfhosted.org>
2021-09-16 07:33:30serhiy.storchakalinkissue45216 messages
2021-09-16 07:33:29serhiy.storchakacreate