Replace `#` comments with modern docstrings when possible

[picnixz]

In string.Formatter.{parse,get_field}, we use simple # comments to document methods. While it's picked up by pydoc (through inspect.getcomments()), it's not picked up by IDEs. I suggest we cleanup those occurrences to improve code readability as well. I stumbled upon it by chance so there might be other places that need such cleanup.

Important

Only comments that are above a def of a public function should be considered. Comments inside the function body or method body should be considered separately as it could also mean that the public API is incompletely documented on purpose (see #134082 (comment) and following).

• Report including private names: https://gist.github.com/picnixz/d4aa5ff5e82013966dc575f0709c4398#file-full-report-md
• Report for publicly-named API: https://gist.github.com/picnixz/d4aa5ff5e82013966dc575f0709c4398#file-report-md

Both reports parse private files as well as they can be re-exported to a public API. We still need to go through each occurrences to check if they are expected to be exposed or not (and thus the task is NOT an easy task for newcomers).

Linked PRs

• gh-134082: Modernize docstrings in string.Formatter #134083
• gh-134082: Modernize docstrings in ArgumentParser.parse_known_intermixed_args #134096
• gh-134082: modernize string.Formatter class docstring #134125

[picnixz]

I found a bunch of other occurrences, most of the time in old places such as html.parser.HTMLParser.parse_starttag:

    # Internal -- handle starttag, return end or -1 if not terminated
    def parse_starttag(self, i):
        self.__starttag_text = None

For internal interfaces, I'm fine leaving them as is, but for public ones, it might be better to use docstrings. It's also a chance to cleanup whitespaces when needed.

I've opened a PR as a PoC but I can close it if it's too much cosmetics (it's borderline cosmetics but there are some pros IMO). Thoughts @AA-Turner @hugovk @serhiy-storchaka?

[StanFromIreland]

Are you looking for help, I can grep the docs later and provide a list of occourances.

[picnixz]

Finding the occurrences isn't really hard. I want to first know whether this is a realistic and desirable feature.

[picnixz]

For example, some IDEs show docstrings on hover (this is PyCharm):

Yes, that's how I found it :')

[ryan-duve]

This would also be useful for IPython. In the vanilla Python interpreter I see:

$ python3
Python 3.12.1 (main, Dec 25 2023, 21:02:37) [GCC 11.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import string
>>> help(string.Formatter.parse)

Help on function parse in module string:

parse(self, format_string)
# returns an iterable that contains tuples of the form:
# (literal_text, field_name, format_spec, conversion)
# literal_text can be zero length
# field_name can be None, in which case there's no
# object to format and output
# if field_name is not None, it is looked up, formatted
# with format_spec and conversion and then used

but in IPython I only see:

In [1]: import string
   ...: 
   ...: 
   ...: string.Formatter.parse??

Signature: string.Formatter.parse(self, format_string)
Docstring:
Source:
def parse(self, format_string):
return _string.formatter_parser(format_string)
File: ~/.pyenv/versions/3.12.1/lib/python3.12/string.py
Type: function