Python文檔字符串：這些文檔字符串參數意味着什麼？

Question

有人可以告訴我以下文檔字符串參數之間的區別嗎？

:type and :param 我已經看到兩者都被用來指定方法參數的類型，但我不認爲它們完全相同。其中一個是程序員，另一個是IDE還是類似的？

:rtype，:return和:returns 特別是：回報和：回報似乎很相似，所以這是在何種情況下使用？

Answer 1

這些約定由Sphinx文檔工具使用，該工具最初是爲處理Python文檔而設計的。然而，它的流行使它被擴展到其他領域，在the Sphinx documentation中被定義爲「一組標記（reStructuredText指令和角色）來描述和鏈接到屬於一起的對象」。

根據連鎖:return頁面來自Python的域，:returns與JavaScript域，並且它們似乎都被用於同樣的事情（即記錄的函數或方法的返回值）。在實踐中:returns顯得很少有人想知道它是否是文檔錯字。

:rtype指定返回類型，如果可能的話將創建一個鏈接類型定義（即如果獅身人面像能找到你的記錄代碼中的定義）。

Answer 2

沒有一個是他們自己的意思。各種程序將掃描一個文檔字符串並解釋某些部分（或標籤），專門用於格式化，鏈接等。按照慣例（從javadoc？開始），此類標籤通常以:開頭。除此之外，具體含義取決於解析文檔字符串的程序，並且沒有定義應該使用什麼標籤的標準。某些程序使用:return來記錄函數的返回值，其他程序使用:rtype。

您的問題的唯一真正的答案是，請參閱您希望處理您的文檔的程序的文檔。