什麼是記錄Perl代碼的最佳方式？

Question

任何建議如何我可以記錄我的Perl代碼？你使用什麼和有什麼工具可以幫助我？

您使用哪個模塊將pod轉換爲html？

Answer 1

幾乎查看任何Perl模塊，您將看到Plain Old Documentation (POD)格式。在CPAN Search上查看模塊時，您可以選擇查看原始數據源，這是您查看原始數據源的一種方法，但您也可以使用命令行中的perldoc。該-m開關顯示了文件

perldoc -m Foo::Bar 

或者，如果你想找到的文件，所以你可以看看它在你喜歡的編輯器，使用-l開關找到它：

perldoc -l Foo::Bar 

一旦你開始記錄你的程序，你把Pod放在代碼中的文件中，或者與代碼交織在一起，所以文檔在相關部分旁邊，或者在開始，中間或結束時作爲一個大塊。

使用Perl附帶的譯碼器（pod2latex，pod2ps，pod2html），Pod可以輕鬆轉換爲其他幾種格式，例如LaTeX，Postscript，HTML等。我甚至有一個轉到InDesign的pod翻譯器。使用Pod::Simple編寫自己的Pod翻譯器非常簡單，所以如果您沒有找到您最喜歡的最終形式的翻譯器，只需自己製作即可。

還有幾種工具可以添加到測試套件中以檢查Pod。 Test::Pod模塊檢查格式錯誤，Test::Pod::Coverage模塊檢查您已記錄每個子例程，等等。您也可能對我的Perl documentation documentation感興趣。

Answer 2

Perl pod。

這就是Mozilla如何記錄他們的Perl。

Answer 3

不要過度翻轉，但記錄Perl代碼的最佳方式與您用任何其他語言編寫代碼的方式相同。

至於具體的工具，我用的標準內聯註釋，莢混合較大的文件，其中類似人的格式是合適的，TeX的大塊作爲需要更自由的文件是最終的後備。 （並且，本着「與其他語言相同」的精神，是的，我也使用pod來記錄非Perl代碼。）

Answer 4

我絕對推薦POD。

POD也可以與代碼一起使用，但我更喜歡在__END__之後放置程序的底部（如Damian Conway在Perl Best Practices中所建議的那樣）。

請看POD::Server & POD::Webserver，它爲您的所有POD提供網絡前端。

Answer 5

您使用哪個模塊將pod 轉換爲html？

退房Pod::ProjectDocs - 你得到一個簡單的命令行實用工具，將所有的POD轉換成你的Perl項目分成一組看起來就像你看到search.cpan.org什麼HTML頁面。

Answer 6

您可能還想看到Damian Conway的Perl Best Practices。我使用了一些技巧來清理我繼承的一個小的Perl代碼庫。

Answer 7

沒有人提到Smart::Comments？這並不總是你想要的，但是如果你需要更多的權力來評論，那就很好。

Answer 8

單獨的用戶文檔和編碼器文檔。也許把用戶文檔（tuts，faq，reference）放在目錄（/ doc）和編碼器的代碼中。不幸的是，它通過修改預期在模塊本身中進行概述。這你可以像已經鋪好的POD後END。鬃毛編碼文件，你可以在評論中。額外的東西，如編碼風格或如何貢獻放在代碼庫（根目錄？）內的獨立.pod文件？