classification
Title: Remove redundant information from difflib docstrings
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, lukasz.langa, miss-islington, pablogsal, serhiy.storchaka, sobolevn, tim.peters
Priority: normal Keywords: patch

Created on 2021-09-16 07:33 by serhiy.storchaka, last changed 2021-10-04 19:18 by pablogsal. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 28445 merged sobolevn, 2021-09-18 10:46
PR 28505 merged miss-islington, 2021-09-21 21:31
PR 28506 merged miss-islington, 2021-09-21 21:31
Messages (5)
msg401923 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2021-09-16 07:33
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.
msg402367 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-09-21 21:31
New changeset 06e1773c8d8fe375423bb7fcf5922b49bc737b75 by Nikita Sobolev in branch 'main':
bpo-45216: Remove extraneous method docs from `difflib` (GH-28445)
https://github.com/python/cpython/commit/06e1773c8d8fe375423bb7fcf5922b49bc737b75
msg402375 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-09-21 21:53
New changeset e6b6c1d23b3702052637f70551451d12695403a1 by Miss Islington (bot) in branch '3.10':
bpo-45216: Remove extraneous method docs from `difflib` (GH-28445) (GH-28505)
https://github.com/python/cpython/commit/e6b6c1d23b3702052637f70551451d12695403a1
msg402378 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-09-21 21:57
New changeset df1006b561f9dca5a15af98d54f0337a75b69445 by Miss Islington (bot) in branch '3.9':
bpo-45216: Remove extraneous method docs from `difflib` (GH-28445) (GH-28506)
https://github.com/python/cpython/commit/df1006b561f9dca5a15af98d54f0337a75b69445
msg403151 - (view) Author: Pablo Galindo Salgado (pablogsal) * (Python committer) Date: 2021-10-04 19:18
New changeset e1eb03d15fa543ea7e3275b213fdb2c649b5968e by Pablo Galindo (Miss Islington (bot)) in branch '3.10':
bpo-45216: Remove extraneous method docs from `difflib` (GH-28445) (GH-28505)
https://github.com/python/cpython/commit/e1eb03d15fa543ea7e3275b213fdb2c649b5968e
History
Date User Action Args
2021-10-04 19:18:41pablogsalsetnosy: + pablogsal
messages: + msg403151
2021-09-21 22:00:55lukasz.langasetstatus: open -> closed
stage: patch review -> resolved
resolution: fixed
versions: + Python 3.9, Python 3.10
2021-09-21 21:57:53lukasz.langasetmessages: + msg402378
2021-09-21 21:53:51lukasz.langasetmessages: + msg402375
2021-09-21 21:31:24miss-islingtonsetpull_requests: + pull_request26901
2021-09-21 21:31:20miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request26900
2021-09-21 21:31:19lukasz.langasetnosy: + lukasz.langa
messages: + msg402367
2021-09-18 14:03:39serhiy.storchakasettitle: Remove redundand information from difflib docstrings -> Remove redundant information from difflib docstrings
2021-09-18 13:08:33rhettingersetnosy: + tim.peters
2021-09-18 10:46:05sobolevnsetkeywords: + patch
nosy: + sobolevn

pull_requests: + pull_request26848
stage: patch review
2021-09-16 07:33:30serhiy.storchakacreate