[New-bugs-announce] [issue45216] Remove redundand information from difflib docstrings

[Serhiy Storchaka]

New submission from Serhiy Storchaka <storchaka+cpython at 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 at python
components: Documentation
messages: 401923
nosy: docs at python, serhiy.storchaka
priority: normal
severity: normal
status: open
title: Remove redundand information from difflib docstrings
type: enhancement
versions: Python 3.11

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue45216>
_______________________________________