我正在使用 Sphinx 從文檔字符串生成文檔，文檔字符串的格式為Sphinx style。根據(jù)PEP-257，我應(yīng)該使用動(dòng)詞“覆蓋”和“擴(kuò)展”來(lái)指示繼承的方法是否被替換或調(diào)用。如果一個(gè)類是另一個(gè)類的子類，并且它的行為主要是從該類繼承的，那么它的文檔字符串應(yīng)該提及這一點(diǎn)并總結(jié)差異。使用動(dòng)詞“override”表示子類方法替換超類方法并且不調(diào)用超類方法；使用動(dòng)詞“extend”來(lái)指示子類方法調(diào)用超類方法（除了它自己的行為之外）。由于我對(duì)此很陌生，因此我不清楚應(yīng)該如何以 Sphinx 格式執(zhí)行此操作。我是否只使用描述中的某個(gè)詞，或者是否有一個(gè)類似的鍵:return:我應(yīng)該應(yīng)用？該指令是在子類級(jí)別給出的，是動(dòng)詞所在的位置還是我也將它們添加到各個(gè)方法中？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")一組簡(jiǎn)單但正確的文檔字符串及其class B方法會(huì)是什么樣子？
1 回答
HUH函數(shù)
TA貢獻(xiàn)1836條經(jīng)驗(yàn) 獲得超4個(gè)贊
直接來(lái)自 Python 文檔的一個(gè)示例是defaultdict集合。它僅覆蓋字典的一種方法（__missing__(key)方法）。
defaultdict 是內(nèi)置 dict 類的子類。它重寫一種方法 (...) 其余功能與 dict 類相同，此處未記錄。(...) 所有剩余參數(shù)的處理方式與傳遞給 dict 構(gòu)造函數(shù)的方式相同，包括關(guān)鍵字論據(jù)。
該文檔以散文形式明確說(shuō)明了這一點(diǎn)，記錄了重寫方法，并解釋了超類和子類構(gòu)造函數(shù)簽名之間的參數(shù)差異。
我是否只使用描述中的某個(gè)單詞，或者這是我需要應(yīng)用的像 :return: 這樣的鍵？
你所說(shuō)的“key”實(shí)際上被稱為文檔字符串部分。沒(méi)有特定的“文檔字符串部分”來(lái)指示“覆蓋”或“擴(kuò)展”，因?yàn)檫@是隱式的。如果子類定義的方法與其超類的方法具有完全相同的名稱，則該方法必然是重寫或擴(kuò)展的。
總之，您會(huì)驚訝地發(fā)現(xiàn)您的文檔實(shí)際上是正確的。您最多可以口頭添加“覆蓋”和“擴(kuò)展”以及對(duì)超類方法的交叉引用，如下所示：
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")
添加回答
舉報(bào)
0/150
提交
取消