## 15\. Rdoc 你正在閱讀本書是因為你正在尋找某種文檔來開始使用 Ruby 進行編程。 文檔在任何類型的編程中都非常重要。 為所編寫的代碼保留良好的文檔記錄可能會使你與優秀的程序員區分開來，并使你成為一個受追捧的人。 本章告訴你兩件事，首先是 Ruby 的核心文檔在哪里，以及如何查找和閱讀它。 第二，它教你如何生成文檔，以便其他人可以更好地理解你的程序。 ### 15.1。 閱讀 Ruby 文檔 假設你想了解 Ruby 程序中的 String 類。 你想知道如何使用 Ruby 來計算姓名中的字符數，那么該怎么做呢？ 訪問此鏈接 [http://ruby-doc.org/](http://ruby-doc.org/) ，這是可獲取紅寶石文檔的集中位置。 現在，如果你可以進行一些操作，你會發現一個東西/鏈接，例如：2.1.4 core-Ruby 2.1.4 的 Core API 文檔。 單擊它，你將定向到此鏈接： [http://ruby-doc.org/core-2.1.4/](http://ruby-doc.org/core-2.1.4/) ，此處記錄了 2.1.4 的核心庫。 可能會出現一個問題，如何找出你使用的紅寶石的版本？ 在終端類型 ruby -v 中，它將拋出如下輸出：ruby 1.9.3p194（2012-04-20 修訂版 35410）[x86_64-linux]，請查看突出顯示的代碼段，這告訴我我正在使用 ruby 1.9.3 分 194。 誰在乎 p194 是什么？ 我知道我使用的是 ruby 1.9.3，所以我要看它的文檔！ 好的，在 [http://ruby-doc.org/core-2.5.1/](http://ruby-doc.org/core-2.5.1/) 中，你需要瀏覽 String，如果這樣做，你會找到以下鏈接： [http：// ruby??- doc.org/core-2.5.1/String.html](http://ruby-doc.org/core-2.5.1/String.html) ，這是 String 類文檔所在的位置。 你可以通過很長的時間（幾乎涵蓋所有內容）或在頂部搜索欄中鍵入 String 來獲得此文檔，在這種情況下，Rdoc 將顯示有效的搜索結果。 下圖顯示我通過在標有 Classes 的文本框中鍵入 Sting 來過濾 Ruby 中的類。 這將幫助我輕松過濾結果/類。  好的，然后，如果你安裝正確，請單擊字符串將你帶到此處 [http://ruby-doc.org/core-2.2.2/String.html](http://ruby-doc.org/core-2.2.2/String.html) 并向下瀏覽，你會找到 稱為#length 的東西，當單擊時會滾動到此處 [http://ruby-doc.org/core-2.2.2/String.html#method-i-length](http://ruby-doc.org/core-2.2.2/String.html#method-i-length) ，所以它確實說我們有東西 /函數/方法稱為長度，另一項稱為大小。 通過有根據的猜測，我們必須能夠知道這就是字符串長度的原因，讓我們在 irb 上進行嘗試 ```rb $ irb --simple-prompt >> "Karthikeyan A K".length => 15 >> "Karthikeyan A K".size => 15 ``` 這樣就行了！ 基本的事情是到達 [http://ruby-doc.org/](http://ruby-doc.org/) 并打破頭腦，這將使事情發展，并使你開始了解閱讀 Ruby 文檔。 ### 15.2。 建立文件 因此，無論你希望還是希望，你可能會或可能不知道閱讀 ruby 的文檔。 讓我們看看如何創建一個。 確定，在名為 [rdoc_square.rb](code/rdoc_square.rb) 的文檔中鍵入以下代碼，或使用你喜歡的任何名稱。 為簡單起見，將其放入文件夾，并確保該文件夾中沒有其他文件。 ```rb #rdoc_square.rb # This class Square takes in side_length (of type float or fixnum) # as argument class Square # The length of a square's side attr_accessor :side_length # Retuns the area of the square def area @side_length * @side_length end # Returns perimeter of the square def perimeter 4 * @side_length end end ``` 請注意，我是如何在屬性和功能之前添加注釋 <sup class="footnote">[ [36](#_footnotedef_36 "View footnote.") ]</sup> 的。 現在，導航到 [rdoc_square.rb](code/rdoc_square.rb) 所在的文件夾（使用控制臺/終端），然后鍵入此命令`rdoc`，就是這樣，神奇的事情發生了。 你會發現創建了一個名為 doc 的文件夾，只需導航到該文件夾??并打開名為 index.html 的文件，然后可以單擊 Classs and Modules Index 框中的 Square 鏈接即可獲得一個漂亮的文檔，如圖所示。  在上圖中的“屬性”部分中，你可以看到 side_length 屬性的文檔，正下方顯示的是它的文檔，其讀取正方形邊的長度。 現在檢查代碼 [rdoc_example.rb](code/rdoc_example.rb) 檢查以下兩行 ```rb class Square # The length of a square's side attr_accessor :side_length ….... end ``` 我們剛剛在文檔頁面上的`attr_accessor :side_length`之前添加了一條注釋行。 這樣，rdoc 決定要放置什么文檔。 它只是檢查在聲明類，變量和函數定義之前發生了什么注釋，并將其放入文檔中，將其整齊地打包，放入漂亮的 CSS（即樣式）和 Javascript（即動態效果<sup class="footnote">） [ [37](#_footnotedef_37 "View footnote.") ]</sup> ），并準備將其提供給你參考。 你可以將代碼以及 doc 文件夾分發給其他人以供參考，這樣人們就可以更好地了解你的代碼，而無需遍歷所有的 ruby 編碼。 這些是生成文檔的步驟 * 將注釋的紅寶石文件放入文件夾 * 通過終端導航到該文件夾??，然后鍵入 rdoc * 你將看到一個名為 doc 的文件夾已創建，只需進入該文件夾并啟動文件 index.html