Replace `#` comments with modern docstrings when possible
Nessuno ha ancora preso questa issue.
- Lingua principale
- Python
- Stelle
- 77.2k
- Fork
- 35.9k
- Metriche di merge delle PR
- Metriche PR in attesa
Descrizione
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
Guida per i contributori
Apri la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Direzione di ricerca
Inizia dai commenti sopra string.Formatter.parse e get_field, quindi esamina i report sull’API pubblica e i report completi collegati nell’issue. Verifica ogni occorrenza segnalata rispetto alla regola per i commenti sopra le funzioni pubbliche, incluso se i nomi privati vengono riesportati. Il lavoro è completato quando le occorrenze appropriate usano docstring moderne, mentre i commenti mantenuti intenzionalmente rimangono invariati; le PR collegate gh-134083, gh-134096 e gh-134125 coprono già attività correlate.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- python
- Ambito
- documentation
- Tipo di issue
- Documentazione
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Stato di attività
- Ferma
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 25/100