Replace `#` comments with modern docstrings when possible
Dieses Issue hat noch niemand übernommen.
- Vorherrschende Sprache
- Python
- Sterne
- 77.2k
- Forks
- 35.9k
- PR-Merge-Kennzahlen
- PR-Kennzahlen ausstehend
Beschreibung
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 adefof 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 https://github.com/python/cpython/issues/134082#issuecomment-2887461014 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-134083
- gh-134096
- gh-134125
Beitragsleitfaden
Erste Schritte
- Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
- Forke das Repository und arbeite in einem Branch.
- Öffne einen Pull Request, der die Issue-Nummer nennt.
Rechercherichtung
Beginne mit den Kommentaren oberhalb von string.Formatter.parse und get_field und prüfe anschließend die im Issue verlinkten Berichte zur public API und die vollständigen Berichte. Überprüfe jedes gemeldete Vorkommen anhand der Regel für Kommentare oberhalb öffentlicher Funktionen, einschließlich der Frage, ob private Namen erneut exportiert werden. Erledigt ist die Aufgabe, wenn die entsprechenden Vorkommen moderne Docstrings verwenden, während absichtlich beibehaltene Kommentare unverändert bleiben; die verlinkten PRs gh-134083, gh-134096 und gh-134125 decken bereits verwandte Arbeiten ab.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- python
- Bereich
- documentation
- Issue-Typ
- Dokumentation
- Schwierigkeit
- 4/5
- Geschätzter Aufwand
- 3-5 Tage
- Aktivitätsstatus
- Veraltet
- Klarheit
- Größtenteils klar
- Anfängerfreundlichkeit
- 25/100