[issue45216] Remove redundand information from difflib docstrings

[Raymond Hettinger]

Change by Raymond Hettinger :


--
nosy: +tim.peters

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45216] Remove redundand information from difflib docstrings

[Nikita Sobolev]

Change by Nikita Sobolev :


--
keywords: +patch
nosy: +sobolevn
nosy_count: 2.0 -> 3.0
pull_requests: +26848
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/28445

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45216] Remove redundand information from difflib docstrings

[Serhiy Storchaka]

New submission from Serhiy Storchaka :

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com