python / python/cpython

Replace `#` comments with modern docstrings when possible

未關閉
#134,082 23 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

還沒有人認領這個 Issue。

docs stdlib type-feature
主要語言
Python
星號
77.2k
分支
35.9k
PR 合併指標
PR 指標待擷取

描述

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 https://github.com/python/cpython/issues/134082#issuecomment-2887461014 and following).

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

貢獻指南

開啟貢獻指南

從這裡開始

  1. 先讀完整個 Issue,再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫,在一個分支上完成修改。
  4. 送出 Pull Request,並在描述裡引用這個 Issue 編號。

研究方向

先從 string.Formatter.parse 和 get_field 上方的註解開始,然後檢視 issue 中連結的 public API 報告和完整報告。根據 public function 上方註解的規則檢查每個回報的出現位置,包括 private 名稱是否被重新匯出。完成的標準是:適當的出現位置使用現代 docstring,同時有意保留的註解維持不變;已連結的 PR gh-134083、gh-134096 和 gh-134125 已涵蓋相關工作。

由索引模型根據 Issue 內容生成。

評估

技術堆疊
python
領域
documentation
Issue 類型
文件
難度
4/5
預估耗時
3-5 天
活躍度
停滯
描述清晰度
基本清楚
新手友好度
25/100

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。