我應該將繼承的方法的perldoc複製到子類的文檔中嗎？

我寫了一個類foo.pm，它從Web服務收集一些數據。在foo.pm裏面，我添加了perldoc來描述功能以及使用簡要指南。其所有方法都有參考。我應該將繼承的方法的perldoc複製到子類的文檔中嗎？

我也寫一個子類cachedFoo.pm，使用foo.pm作爲基類，環繞foo的new方法自身的構造和升級foo與數據庫連接，緩存結果。我已經添加了perldoc到cachedFoo.pm的額外的東西。

現在我只想讓我的同事使用cachedFoo.pm。我是否應該將所有從foo.pm繼承的方法的perldoc複製到cachedFoo.pm，或者我應該說「查看基類的訪問器文檔」？或者有另一種方式？

2012-07-18 simbabque

只需在接口描述開始時指向其他類就足夠了，請參閱下面的最佳實踐文檔示例。你的pod覆蓋率測試應該使用Pod::Coverage::CountParents來考慮遺傳。

package cachedFoo; 
⋮ 
=head1 INTERFACE 

=head2 Composition 

    cachedFoo 
     ISA foo 
     DOES somerole 

All methods and attributes not mentioned here are 
inherited from L<foo> or mixed in from L<somerole>. 

=head2 Methods 

=head3 C<cache_database_thing> 

Blah blah blah, Mr. Freeman

明確命名每個組合方法不會縮放。我不能推薦這個：

=head3 C<quux> 

See L<foo/quux>.

來源

2012-07-18 15:17:38 daxim

我想我會用這個例子，謝謝你 – simbabque 2012-07-19 20:32:42

不要複製文檔，它會不同步，只是提供指向原始文檔的鏈接並記錄差異。

來源

2012-07-18 13:27:52 kixx

這是我的擔憂之一 – simbabque 2012-07-18 13:50:48

你應該考慮重命名你的模塊。我認爲Foo :: Cached將是常見做法。我通常表明繼承只有在相關的章節，例如：

=head1 METHODS 

L<Foo::Cached> inherits all methods from L<Foo> and implements the following methods by itself: 

...

如果你仍然想看到所有的繼承方法，你可以使用Pod::Inherit創建一個臨時podfile其中還包括POD從主模塊（或者，如果你你可以嘗試Pod::Weaver

來源

2012-07-18 15:39:32

感謝您對命名約定的提示，我想到了，但wasn 't sure。 – simbabque 2012-07-18 17:24:07

關於這個命名約定：如果只有一個子類，你還會這麼做嗎？ – simbabque 2012-07-19 20:27:49

是的，我會。 **特別是**如果其他程序員也會使用該代碼。 Unnested模塊名稱只會導致混淆，特別是在大型項目中。選擇嵌套名稱也可以防止兼容性問題。有些文件系統將它們的文件名長度限制爲8.3字符，所以'cachedFoo'可能已經太長了...... – 2012-07-19 23:07:17

我應該將繼承的方法的perldoc複製到子類的文檔中嗎？

回答

相關問題