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

Improve docstring for str.index #73735

Closed
rhettinger opened this issue Feb 13, 2017 · 17 comments
Closed

Improve docstring for str.index #73735

rhettinger opened this issue Feb 13, 2017 · 17 comments
Assignees
Labels
3.7 (EOL) end of life docs Documentation in the Doc dir

Comments

@rhettinger
Copy link
Contributor

BPO 29549
Nosy @rhettinger, @ncoghlan, @benhoyt, @serhiy-storchaka, @zhangyangyu, @lisroach, @Mariatta, @CuriousLearner
PRs
  • bpo-29549: Fixes docstring for str.index #147
  • bpo-29602: fix signed zero handling in complex constructor #204
  • bpo-29549: Fixes docstring for str.index #256
  • [3.6] bpo-29549: Fixes docstring for str.index (GH-256) #1028
  • 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 = 'https://github.com/lisroach'
    closed_at = <Date 2017-04-05.06:32:02.545>
    created_at = <Date 2017-02-13.20:57:22.161>
    labels = ['3.7', 'docs']
    title = 'Improve docstring for str.index'
    updated_at = <Date 2017-04-10.21:38:58.744>
    user = 'https://github.com/rhettinger'

    bugs.python.org fields:

    activity = <Date 2017-04-10.21:38:58.744>
    actor = 'Mariatta'
    assignee = 'lisroach'
    closed = True
    closed_date = <Date 2017-04-05.06:32:02.545>
    closer = 'rhettinger'
    components = ['Documentation']
    creation = <Date 2017-02-13.20:57:22.161>
    creator = 'rhettinger'
    dependencies = []
    files = []
    hgrepos = []
    issue_num = 29549
    keywords = []
    message_count = 17.0
    messages = ['287724', '288025', '288027', '288234', '288235', '288353', '288354', '288402', '288404', '288405', '288408', '288465', '288470', '288494', '291154', '291159', '291397']
    nosy_count = 8.0
    nosy_names = ['rhettinger', 'ncoghlan', 'benhoyt', 'serhiy.storchaka', 'xiang.zhang', 'lisroach', 'Mariatta', 'CuriousLearner']
    pr_nums = ['147', '204', '256', '1028']
    priority = 'normal'
    resolution = 'fixed'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = None
    url = 'https://bugs.python.org/issue29549'
    versions = ['Python 3.6', 'Python 3.7']

    @rhettinger
    Copy link
    Contributor Author

    The docstring for str.index() needs to be synced with the main documentation rather than presuming knowledge of str.find().

    Currently it reads:

    >>> help(str.index)
    Help on method_descriptor:
    index(...)
        S.index(sub[, start[, end]]) -> int
        
        Like S.find() but raise ValueError when the substring is not found.

    And it should read more like str.find:

    help(str.find)
    Help on method_descriptor:
    
    find(...)
        S.find(sub[, start[, end]]) -> int
        
        Return the lowest index in S where substring sub is found,
        such that sub is contained within S[start:end].  Optional
        arguments start and end are interpreted as in slice notation.
        
        Return -1 on failure.

    Lisa, it would be great if you could draft-up a patch.

    @rhettinger rhettinger added the 3.7 (EOL) end of life label Feb 13, 2017
    @rhettinger rhettinger added the docs Documentation in the Doc dir label Feb 13, 2017
    @benhoyt
    Copy link
    Mannequin

    benhoyt mannequin commented Feb 17, 2017

    Good call. Additionally, it's weird to me that the docstring for str.find() says "Return -1 on failure." because the string not being found is not a "failure". Like the docs (https://docs.python.org/3.5/library/stdtypes.html#str.find) say, the str.find() docstring should say "Return -1 if sub is not found."

    @serhiy-storchaka
    Copy link
    Member

    str.index() still is not converted to Argument Clinic (this is not easy). The docstring needs to be rewritten when convert it to Argument Clinic in any case. It would be nice to make it Argument Clinic compatible right now. The first line line should be short description, following paragraph(s) can describe more details, the description shouldn't refer to the metavariable S.

    Docstrings for str, bytes and bytearray methods should be synchronised. Look also at docstrings for the index() method in other sequence types (list, tuple, deque, array, Sequence).

    @lisroach
    Copy link
    Contributor

    I tried to have a go at making the str.index Argument Clinic compatible, Serhiy can you take a look at my commits and let me know if this is the correct way of doing it:

    master...lisroach:master

    If it looks good I will make a pull request. Thanks!

    @serhiy-storchaka
    Copy link
    Member

    No need to add Argument Clinic code. Just make docstrings in the style of of Argument Clinic descriptions.

    @Mariatta
    Copy link
    Member

    CuriousLearner,

    I see that you have PRs against this issue.
    The issue is currently assigned to Lisa.
    I respectfully request that you choose a different issue to work on and to withdraw your pull request.

    Please choose an issue that is not currently assigned to anyone. If an issue is assigned, please ask first before working on it.

    Thank you.

    @CuriousLearner
    Copy link
    Member

    Mariatta, I apologize for this. I completely missed to see that this was already assigned to someone else.

    I've withdrawn my PR.

    Thanks.

    @rhettinger
    Copy link
    Contributor Author

    Serhiy, I'm not sure what you're referring to by "Just make docstrings in the style of of Argument Clinic descriptions". For the time being, I would like the docstring to match that of str.find(). The point of the patch is to decouple the two.

    AC issues and migrations can wait. At this point, AC adoption has been more disruptive that helpful in a number of cases.

    @zhangyangyu
    Copy link
    Member

    Lisa, could you make a PR? It could let more developers see your patch.

    @rhettinger
    Copy link
    Contributor Author

    Please everyone. Ease up. This is a very simple patch. Copy what is done in str.find to str.index. It doesn't need infinite discussion and debate. I assigned this to Lisa to give her practice. It wasn't intended to have five developers jump in and shove it back and forth. Let's let simple things be simple and not waste the time of new contributors.

    @serhiy-storchaka
    Copy link
    Member

    I mean that this work is useless since it will be lost when convert str.index to Argument Clinic. Well, even when don't use Argument Clinic, but make str.index() be supported by inspect.signature(), the docstring should be significantly rewritten.

    I think there are many other easy documentation issues for practicing.

    And all proposed PRs change only the docstring of str.index. They don't touch docstrings of str.rindex, bytes.index, bytes.rindex, bytearray.index and bytearray.rindex. I can't approve such changes.

    @lisroach
    Copy link
    Contributor

    I'll just go ahead and make my PR, let me know what else needs to be done.

    Serhiy, if you could point me in the direction of how to write the docstring so that it is in the Argument Clinic style I would be happy to take a look.

    @Mariatta
    Copy link
    Member

    Thanks for the PR, Lisa.

    Serhiy, Raymond, could you both review this? Thanks.
    I can do the merge and backport once it gets both of your approval :)

    Also,should this be applied to 3.5 too?

    @serhiy-storchaka
    Copy link
    Member

    Write docstrings in following style:

    "index($self, sub, start=0, end=sys.maxsize, /)\n"
    "--\n"
    "\n"
    "<The summary line>\n"
    "\n"
    "<Rest of multiline\n"
    "description>"

    Extract the summary line. Don't use the metavariable "S" since it no longer defined in the signature.

    @rhettinger
    Copy link
    Contributor Author

    New changeset 43ba886 by Raymond Hettinger (Lisa Roach) in branch 'master':
    bpo-29549: Fixes docstring for str.index (#256)
    43ba886

    @rhettinger
    Copy link
    Contributor Author

    Thanks Lisa.

    @Mariatta
    Copy link
    Member

    Mariatta commented Apr 9, 2017

    New changeset 577fc04 by Mariatta in branch '3.6':
    [3.6] bpo-29549: Fixes docstring for str.index (GH-256) (GH-1028)
    577fc04

    @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.7 (EOL) end of life docs Documentation in the Doc dir
    Projects
    None yet
    Development

    No branches or pull requests

    6 participants