Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove redundant information from difflib docstrings #89379

Closed
serhiy-storchaka opened this issue Sep 16, 2021 · 5 comments
Closed

Remove redundant information from difflib docstrings #89379

serhiy-storchaka opened this issue Sep 16, 2021 · 5 comments
Labels
3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@serhiy-storchaka
Copy link
Member

BPO 45216
Nosy @tim-one, @ambv, @serhiy-storchaka, @pablogsal, @miss-islington, @sobolevn
PRs
  • bpo-45216: removes extra method docs from difflib #28445
  • [3.10] bpo-45216: Remove extraneous method docs from difflib (GH-28445) #28505
  • [3.9] bpo-45216: Remove extraneous method docs from difflib (GH-28445) #28506
  • Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
    closed_at = <Date 2021-09-21.22:00:55.821>
    created_at = <Date 2021-09-16.07:33:30.186>
    labels = ['3.11', 'type-feature', '3.9', '3.10', 'docs']
    title = 'Remove redundant information from difflib docstrings'
    updated_at = <Date 2021-10-04.19:18:41.827>
    user = 'https://github.com/serhiy-storchaka'

    bugs.python.org fields:

    activity = <Date 2021-10-04.19:18:41.827>
    actor = 'pablogsal'
    assignee = 'docs@python'
    closed = True
    closed_date = <Date 2021-09-21.22:00:55.821>
    closer = 'lukasz.langa'
    components = ['Documentation']
    creation = <Date 2021-09-16.07:33:30.186>
    creator = 'serhiy.storchaka'
    dependencies = []
    files = []
    hgrepos = []
    issue_num = 45216
    keywords = ['patch']
    message_count = 5.0
    messages = ['401923', '402367', '402375', '402378', '403151']
    nosy_count = 7.0
    nosy_names = ['tim.peters', 'docs@python', 'lukasz.langa', 'serhiy.storchaka', 'pablogsal', 'miss-islington', 'sobolevn']
    pr_nums = ['28445', '28505', '28506']
    priority = 'normal'
    resolution = 'fixed'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = 'enhancement'
    url = 'https://bugs.python.org/issue45216'
    versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

    @serhiy-storchaka
    Copy link
    Member Author

    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.

    @serhiy-storchaka serhiy-storchaka added the 3.11 only security fixes label Sep 16, 2021
    @serhiy-storchaka serhiy-storchaka added docs Documentation in the Doc dir type-feature A feature request or enhancement 3.11 only security fixes labels Sep 16, 2021
    @serhiy-storchaka serhiy-storchaka added docs Documentation in the Doc dir type-feature A feature request or enhancement labels Sep 16, 2021
    @serhiy-storchaka serhiy-storchaka changed the title Remove redundand information from difflib docstrings Remove redundant information from difflib docstrings Sep 18, 2021
    @serhiy-storchaka serhiy-storchaka changed the title Remove redundand information from difflib docstrings Remove redundant information from difflib docstrings Sep 18, 2021
    @ambv
    Copy link
    Contributor

    ambv commented Sep 21, 2021

    New changeset 06e1773 by Nikita Sobolev in branch 'main':
    bpo-45216: Remove extraneous method docs from difflib (GH-28445)
    06e1773

    @ambv
    Copy link
    Contributor

    ambv commented Sep 21, 2021

    New changeset e6b6c1d by Miss Islington (bot) in branch '3.10':
    bpo-45216: Remove extraneous method docs from difflib (GH-28445) (GH-28505)
    e6b6c1d

    @ambv
    Copy link
    Contributor

    ambv commented Sep 21, 2021

    New changeset df1006b by Miss Islington (bot) in branch '3.9':
    bpo-45216: Remove extraneous method docs from difflib (GH-28445) (GH-28506)
    df1006b

    @ambv ambv added 3.9 only security fixes 3.10 only security fixes labels Sep 21, 2021
    @ambv ambv closed this as completed Sep 21, 2021
    @ambv ambv added 3.9 only security fixes 3.10 only security fixes labels Sep 21, 2021
    @ambv ambv closed this as completed Sep 21, 2021
    @pablogsal
    Copy link
    Member

    New changeset e1eb03d by Pablo Galindo (Miss Islington (bot)) in branch '3.10':
    bpo-45216: Remove extraneous method docs from difflib (GH-28445) (GH-28505)
    e1eb03d

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    None yet
    Development

    No branches or pull requests

    3 participants