我正在使用 Sphinx 從文檔字符串生成文檔，文檔字符串的格式為Sphinx style。根據PEP-257，我應該使用動詞“覆蓋”和“擴展”來指示繼承的方法是否被替換或調用。如果一個類是另一個類的子類，并且它的行為主要是從該類繼承的，那么它的文檔字符串應該提及這一點并總結差異。使用動詞“override”表示子類方法替換超類方法并且不調用超類方法；使用動詞“extend”來指示子類方法調用超類方法（除了它自己的行為之外）。由于我對此很陌生，因此我不清楚應該如何以 Sphinx 格式執行此操作。我是否只使用描述中的某個詞，或者是否有一個類似的鍵:return:我應該應用？該指令是在子類級別給出的，是動詞所在的位置還是我也將它們添加到各個方法中？class A: """This is my base class.""" def method_a(self): """My base method a.""" pass def method_b(self): """My base method b.""" passclass B(A): """This is the subclass that inherits from :class: A.""" def method_a(self): """This method replaces the inherited method_a.""" print("overridden") def method_b(self): """This method calls the inherited method_b.""" super(B, self).method_b() print("extended")一組簡單但正確的文檔字符串及其class B方法會是什么樣子？
1 回答
HUH函數
TA貢獻1836條經驗 獲得超4個贊
直接來自 Python 文檔的一個示例是defaultdict集合。它僅覆蓋字典的一種方法（__missing__(key)方法）。
defaultdict 是內置 dict 類的子類。它重寫一種方法 (...) 其余功能與 dict 類相同，此處未記錄。(...) 所有剩余參數的處理方式與傳遞給 dict 構造函數的方式相同，包括關鍵字論據。
該文檔以散文形式明確說明了這一點，記錄了重寫方法，并解釋了超類和子類構造函數簽名之間的參數差異。
我是否只使用描述中的某個單詞，或者這是我需要應用的像 :return: 這樣的鍵？
你所說的“key”實際上被稱為文檔字符串部分。沒有特定的“文檔字符串部分”來指示“覆蓋”或“擴展”，因為這是隱式的。如果子類定義的方法與其超類的方法具有完全相同的名稱，則該方法必然是重寫或擴展的。
總之，您會驚訝地發現您的文檔實際上是正確的。您最多可以口頭添加“覆蓋”和“擴展”以及對超類方法的交叉引用，如下所示：
class B(A):
? ? """Neither method_a nor method_b are inherited.
? ? ? ?Both methods are redefined in this class.
? ? """
? ? def method_a(self):
? ? ? ? """This method overrides :meth:`A.method_a`."""
? ? ? ? print("overridden")
? ? def method_b(self):
? ? ? ? """This method extends :meth:`A.method_b`."""
? ? ? ? super().method_b()
? ? ? ? print("extended")
添加回答
舉報
0/150
提交
取消