Windows PowerShell：借助註解
您可以在指令碼中加入自己的註解，建立自己的線上說明和教學課程系統。
Don Jones
有關 Windows PowerShell 的優雅的事情之一是其説明系統。 説明檔包括語法概述、 詳細的解釋、 示例等等。
考慮到一個命令列的 shell 不能提供可發現性功能，例如內容功能表、 工具列、 色帶等，説明檔站在自己作為可發現性的功能。 您可以使用它帶有萬用字元，例如，以發現新的命令。 然後，您可以閱讀他們的説明，以瞭解如何使用它們。
如您作為函數和腳本生成您自己的命令，您將很好地你的工作一樣拋光作為本機 Windows PowerShell Cmdlet。 您應當始終努力使您的工作盡可能符合外殼程式的其餘部分。 這種一致性和波蘭的部分是如何編寫和提供説明。
您可以生成精確相同種類的 Windows PowerShell 本身使用的基於 XML 的説明檔。 有更多的討論，關於這一主題在我自助出版的書，"Windows PowerShell 腳本和工具製造"。然而，你們中的大部分不需要的那些説明提供，例如，能夠提供多種語言的説明檔的靈活性。
您可以很容易的路線。 您只可以使用基於注釋的説明。
基於注釋的説明規則
有幾個規則的基於注釋的説明我應右掩蓋前面：
- 通常情況下，您需要將括在您特別注釋塊 < # 塊評論 #> 標記。 它也是合法的只是從它開始 # 注釋字元評論每一條線。
- 基於注釋的説明應該是在指令檔中的第一件事。 最好的是，以包括在該函數內，而不是只是之前的説明。 這有助於保持注釋"部分"的功能，並可確保 Windows PowerShell 不會混淆它來的東西。 它也是合法的將該腳本的基於注釋的説明放在檔的末尾，但我不喜歡這樣做，因為它減少了一些使用基於注釋的説明的其他好處。
- 如果你的公司為函數提供的説明，在基於注釋的説明塊可以來之前或立即之後的函數名稱和打開花括弧。
- 當您將多個函數放入一個腳本，腳本模組，如可以通過將注釋塊放在頂部為檔提供説明。 所以，任何隨後的特定函數的説明將站相距不正確，則請確保該注釋塊之後, 添加至少幾個空行。
- 如果你拼錯任何基於注釋的説明關鍵字，Windows PowerShell 可能只是忽略整個塊。 所以要小心你的拼寫，因為它計數。
基於注釋的説明語法
基於注釋的説明由一個或多個部分組成。 每一節開頭虛線的關鍵字後, 跟由一行或多行的文本。 範例：
<# .SYNOPSIS The synopsis goes here. This can be one line, or many. .DESCRIPTION The description is usually a longer, more detailed explanation of what the script or function does. Take as many lines as you need. .PARAMETER computername Here, the dotted keyword is followed by a single parameter name. Don't precede that with a hyphen. The following lines describe the purpose of the parameter: .PARAMETER filePath Provide a PARAMETER section for each parameter that your script or function accepts. .EXAMPLE There's no need to number your examples. .EXAMPLE PowerShell will number them for you when it displays your help text to a user. #>
該示例包含四個最常用的虛線的關鍵字。 您會注意到這些開始用圓點或句點。 Windows PowerShell 不是關於那些區分大小寫，雖然檔列出他們的所有大寫 （所以我傾向于這樣做）。 使用全部大寫也使得有點更當你在閱讀的代碼在腳本編輯器中脫穎而出的部分。
您可以使用的一個其他整潔的截面是連結。 這一點，您可以包含一個 URL，開始為 HTTP:// 位址，對你的説明的連線版本。 張貼在 intranet 網站上，您的説明，例如允許某人獲取更多詳細資訊，可能會更多的例子，找出如何與您聯繫，等等。
Windows PowerShell 自動生成額外的説明內容來看您的腳本或函數。 它派生的名稱、 （包括參數名和資料類型） 的基本語法和其他資訊。 它不在參數中檢測您可能已編碼的任何預設值：
Param($computername = 'localhost')
因此，您應注意文檔參數本身，説明中或甚至在描述中的任何預設值。
基於注釋的精彩表現
基於注釋的另一個優點是説明的説明的它提供了兩個種類。 一個是為那些對您的腳本和職能運行的説明。 另一個用於閱讀您的腳本的人。
換句話說，寫得很好的基於注釋的説明可以還兼作行中的文檔，您可能更願意將放在任何種您的腳本。
.jpg)
Don Jones 是一個 Microsoft MVP 獎收件者和"學習 Windows PowerShell 中月的午餐"(曼甯出版物，2011年），旨在説明成為有效與 Windows PowerShell 任何管理員一書的作者。 鐘斯還提供公共和現場 Windows PowerShell 培訓。 與通過他聯繫 ConcentratedTech.com 或 bit.ly/AskDon。