From 82f8f146c62a7435dc061eae9e224db23a215e13 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 23 Sep 2025 16:26:34 -0500 Subject: [PATCH] Update docs on comment-based help (#12375) --- .../About/about_Comment_Based_Help.md | 18 +-- .../About/about_Comment_Based_Help.md | 18 +-- .../About/about_Comment_Based_Help.md | 18 +-- .../About/about_Comment_Based_Help.md | 18 +-- .../help/comment-based-help-keywords.md | 134 ++++++++---------- .../developer/help/naming-help-files.md | 10 +- ...ing-help-for-windows-powershell-modules.md | 101 +++++++------ 7 files changed, 167 insertions(+), 150 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index 142e7c5ae2c1..f49756982b8f 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -324,14 +324,16 @@ comment-based help, even if it can't find a help topic that matches the value of the `.EXTERNALHELP` keyword. If the function is exported by a module, set the value of the `.EXTERNALHELP` -keyword to a filename without a path. `Get-Help` looks for the specified file -name in a language-specific subdirectory of the module directory. There are no -requirements for the name of the XML-based help file for a function, but a best -practice is to use the following format: - -```Syntax --help.xml -``` +keyword to a filename without a path. `Get-Help` looks for the specified +filename in a language-specific subdirectory of the module directory. There are +no requirements for the name of the XML-based help file for a function. +Beginning in PowerShell 5.0, functions that are exported by a module can be +documented in a help file that's named for the module. You don't need to use +`.EXTERNALHELP` comment keyword. For example, if the `Test-Function` function +is exported by the `MyModule` module, you can name the help file +`MyModule-help.xml`. The `Get-Help` cmdlet looks for help for the +`Test-Function` function in the `MyModule-help.xml` file in the module +directory. If the function isn't included in a module, include a path to the XML-based help file. If the value includes a path and the path contains diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index 8bc3e827c92e..0c6e11a77ee5 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -324,14 +324,16 @@ comment-based help, even if it can't find a help topic that matches the value of the `.EXTERNALHELP` keyword. If the function is exported by a module, set the value of the `.EXTERNALHELP` -keyword to a filename without a path. `Get-Help` looks for the specified file -name in a language-specific subdirectory of the module directory. There are no -requirements for the name of the XML-based help file for a function, but a best -practice is to use the following format: - -```Syntax --help.xml -``` +keyword to a filename without a path. `Get-Help` looks for the specified +filename in a language-specific subdirectory of the module directory. There are +no requirements for the name of the XML-based help file for a function. +Beginning in PowerShell 5.0, functions that are exported by a module can be +documented in a help file that's named for the module. You don't need to use +`.EXTERNALHELP` comment keyword. For example, if the `Test-Function` function +is exported by the `MyModule` module, you can name the help file +`MyModule-help.xml`. The `Get-Help` cmdlet looks for help for the +`Test-Function` function in the `MyModule-help.xml` file in the module +directory. If the function isn't included in a module, include a path to the XML-based help file. If the value includes a path and the path contains diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index 7e9a1673092e..97894d881fa0 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -324,14 +324,16 @@ comment-based help, even if it can't find a help topic that matches the value of the `.EXTERNALHELP` keyword. If the function is exported by a module, set the value of the `.EXTERNALHELP` -keyword to a filename without a path. `Get-Help` looks for the specified file -name in a language-specific subdirectory of the module directory. There are no -requirements for the name of the XML-based help file for a function, but a best -practice is to use the following format: - -```Syntax --help.xml -``` +keyword to a filename without a path. `Get-Help` looks for the specified +filename in a language-specific subdirectory of the module directory. There are +no requirements for the name of the XML-based help file for a function. +Beginning in PowerShell 5.0, functions that are exported by a module can be +documented in a help file that's named for the module. You don't need to use +`.EXTERNALHELP` comment keyword. For example, if the `Test-Function` function +is exported by the `MyModule` module, you can name the help file +`MyModule-help.xml`. The `Get-Help` cmdlet looks for help for the +`Test-Function` function in the `MyModule-help.xml` file in the module +directory. If the function isn't included in a module, include a path to the XML-based help file. If the value includes a path and the path contains diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index b0760b190ac0..34f60e91466d 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -324,14 +324,16 @@ comment-based help, even if it can't find a help topic that matches the value of the `.EXTERNALHELP` keyword. If the function is exported by a module, set the value of the `.EXTERNALHELP` -keyword to a filename without a path. `Get-Help` looks for the specified file -name in a language-specific subdirectory of the module directory. There are no -requirements for the name of the XML-based help file for a function, but a best -practice is to use the following format: - -```Syntax --help.xml -``` +keyword to a filename without a path. `Get-Help` looks for the specified +filename in a language-specific subdirectory of the module directory. There are +no requirements for the name of the XML-based help file for a function. +Beginning in PowerShell 5.0, functions that are exported by a module can be +documented in a help file that's named for the module. You don't need to use +`.EXTERNALHELP` comment keyword. For example, if the `Test-Function` function +is exported by the `MyModule` module, you can name the help file +`MyModule-help.xml`. The `Get-Help` cmdlet looks for help for the +`Test-Function` function in the `MyModule-help.xml` file in the module +directory. If the function isn't included in a module, include a path to the XML-based help file. If the value includes a path and the path contains diff --git a/reference/docs-conceptual/developer/help/comment-based-help-keywords.md b/reference/docs-conceptual/developer/help/comment-based-help-keywords.md index 1cb7b8473e38..e11ea17807ce 100644 --- a/reference/docs-conceptual/developer/help/comment-based-help-keywords.md +++ b/reference/docs-conceptual/developer/help/comment-based-help-keywords.md @@ -1,6 +1,6 @@ --- description: Comment-Based Help Keywords -ms.date: 05/21/2025 +ms.date: 09/22/2025 no-loc: [FAQ, Function, General, Glossary, Provider, Component, Functionality, Role] title: Comment-Based Help Keywords --- @@ -20,46 +20,41 @@ when it can't find a help file that matches the value of the keyword. ## `.SYNOPSIS` -A brief description of the function or script. This keyword can be used only -once in each topic. +A brief description of the function or script. This keyword can be used only once in each topic. ## `.DESCRIPTION` -A detailed description of the function or script. This keyword can be used only -once in each topic. +A detailed description of the function or script. This keyword can be used only once in each topic. ## `.PARAMETER ` -The description of a parameter. You can include a `.PARAMETER` keyword for each -parameter in the function or script. +The description of a parameter. You can include a `.PARAMETER` keyword for each parameter in the +function or script. -The `.PARAMETER` keywords can appear in any order in the comment block, but the -order in which the parameters appear in the `param` statement or function -declaration determines the order in which the parameters appear in Help topic. -To change the order of parameters in the Help topic, change the order of the -parameters in the `param` statement or function declaration. +The `.PARAMETER` keywords can appear in any order in the comment block, but the order in which the +parameters appear in the `param` statement or function declaration determines the order in which the +parameters appear in Help topic. To change the order of parameters in the Help topic, change the +order of the parameters in the `param` statement or function declaration. -You can also specify a parameter description by placing a comment in the -`param` statement immediately before the parameter variable name. If you use -both a `param` statement comment and a `.PARAMETER` keyword, the description -associated with the `.PARAMETER` keyword is used, and the `param` statement -comment is ignored. +You can also specify a parameter description by placing a comment in the `param` statement +immediately before the parameter variable name. If you use both a `param` statement comment and a +`.PARAMETER` keyword, the description associated with the `.PARAMETER` keyword is used, and the +`param` statement comment is ignored. ## `.EXAMPLE` -A sample command that uses the function or script, optionally followed by -sample output and a description. Repeat this keyword for each example. +A sample command that uses the function or script, optionally followed by sample output and a +description. Repeat this keyword for each example. ## `.INPUTS` -The .NET types of objects that can be piped to the function or script. You can -also include a description of the input objects. Repeat this keyword for each -input type. +The .NET types of objects that can be piped to the function or script. You can also include a +description of the input objects. Repeat this keyword for each input type. ## `.OUTPUTS` -The .NET type of the objects that the cmdlet returns. You can also include a -description of the returned objects. Repeat this keyword for each output type. +The .NET type of the objects that the cmdlet returns. You can also include a description of the +returned objects. Repeat this keyword for each output type. ## `.NOTES` @@ -67,36 +62,33 @@ Additional information about the function or script. ## `.LINK` -The name of a related topic. Repeat this keyword for each related topic. This -content appears in the Related Links section of the Help topic. +The name of a related topic. Repeat this keyword for each related topic. This content appears in the +Related Links section of the Help topic. -The `.LINK` keyword content can also include a Uniform Resource Identifier -(URI) to an online version of the same help topic. The online version opens -when you use the **Online** parameter of `Get-Help`. The URI must begin with -`http` or `https`. +The `.LINK` keyword content can also include a Uniform Resource Identifier (URI) to an online +version of the same help topic. The online version opens when you use the **Online** parameter of +`Get-Help`. The URI must begin with `http` or `https`. ## `.COMPONENT` -The name of the technology or feature that the function or script uses, or to -which it's related. The **Component** parameter of `Get-Help` uses this value -to filter the search results returned by `Get-Help`. +The name of the technology or feature that the function or script uses, or to which it's related. +The **Component** parameter of `Get-Help` uses this value to filter the search results returned by +`Get-Help`. ## `.ROLE` -The name of the user role for the help topic. The **Role** parameter of -`Get-Help` uses this value to filter the search results returned by `Get-Help`. +The name of the user role for the help topic. The **Role** parameter of `Get-Help` uses this value +to filter the search results returned by `Get-Help`. ## `.FUNCTIONALITY` -The keywords that describe the intended use of the function. The -**Functionality** parameter of `Get-Help` uses this value to filter the search -results returned by `Get-Help`. +The keywords that describe the intended use of the function. The **Functionality** parameter of +`Get-Help` uses this value to filter the search results returned by `Get-Help`. ## `.FORWARDHELPTARGETNAME ` -Redirects to the help topic for the specified command. You can redirect users -to any help topic, including help content for a function, script, cmdlet, or -provider. +Redirects to the help topic for the specified command. You can redirect users to any help topic, +including help content for a function, script, cmdlet, or provider. ```powershell # .FORWARDHELPTARGETNAME @@ -104,10 +96,10 @@ provider. ## `.FORWARDHELPCATEGORY` -Specifies the help category of the item in `.FORWARDHELPTARGETNAME`. Valid -values are `Alias`, `Cmdlet`, `HelpFile`, `Function`, `Provider`, `General`, -`FAQ`, `Glossary`, `ScriptCommand`, `ExternalScript`, `Filter`, or `All`. Use -this keyword to avoid conflicts when there are commands with the same name. +Specifies the help category of the item in `.FORWARDHELPTARGETNAME`. Valid values are `Alias`, +`Cmdlet`, `HelpFile`, `Function`, `Provider`, `General`, `FAQ`, `Glossary`, `ScriptCommand`, +`ExternalScript`, `Filter`, or `All`. Use this keyword to avoid conflicts when there are commands +with the same name. ```powershell # .FORWARDHELPCATEGORY @@ -115,10 +107,9 @@ this keyword to avoid conflicts when there are commands with the same name. ## `.REMOTEHELPRUNSPACE ` -Specifies a session that contains the help topic. Enter a variable that -contains a **PSSession** object. This keyword is used by the -[Export-PSSession][09] cmdlet to find the help content for the exported -commands. +Specifies a session that contains the help topic. Enter a variable that contains a **PSSession** +object. This keyword is used by the [Export-PSSession][09] cmdlet to find the help content for the +exported commands. ```powershell # .REMOTEHELPRUNSPACE @@ -132,31 +123,26 @@ Specifies an XML-based help file for the script or function. # .EXTERNALHELP ``` -The `.EXTERNALHELP` keyword is required when a function or script is documented -in XML files. Without this keyword, `Get-Help` can't find the XML-based help -file for the function or script. - -The `.EXTERNALHELP` keyword takes precedence over other comment-based help -keywords. If `.EXTERNALHELP` is present, `Get-Help` doesn't display -comment-based help, even if it can't find a help topic that matches the value -of the `.EXTERNALHELP` keyword. - -If the function is exported by a module, set the value of the `.EXTERNALHELP` -keyword to a filename without a path. `Get-Help` looks for the specified file -name in a language-specific subdirectory of the module directory. There are no -requirements for the name of the XML-based help file for a function, but a best -practice is to use the following format: - -```Syntax --help.xml -``` - -If the function isn't included in a module, include a path to the XML-based -help file. If the value includes a path and the path contains -UI-culture-specific subdirectories, `Get-Help` searches the subdirectories -recursively for an XML file with the name of the script or function in -accordance with the language fallback standards established for Windows, just -as it does in a module directory. +The `.EXTERNALHELP` keyword is required when a function or script is documented in XML files. +Without this keyword, `Get-Help` can't find the XML-based help file for the function or script. + +The `.EXTERNALHELP` keyword takes precedence over other comment-based help keywords. If +`.EXTERNALHELP` is present, `Get-Help` doesn't display comment-based help, even if it can't find a +help topic that matches the value of the `.EXTERNALHELP` keyword. + +If the function is exported by a module, set the value of the `.EXTERNALHELP` keyword to a filename +without a path. `Get-Help` looks for the specified filename in a language-specific subdirectory of +the module directory. There are no requirements for the name of the XML-based help file for a +function. Beginning in PowerShell 5.0, functions that are exported by a module can be documented in +a help file that's named for the module. You don't need to use `.EXTERNALHELP` comment keyword. For +example, if the `Test-Function` function is exported by the `MyModule` module, you can name the help +file `MyModule-help.xml`. The `Get-Help` cmdlet looks for help for the `Test-Function` function in +the `MyModule-help.xml` file in the module directory. + +If the function isn't included in a module, include a path to the XML-based help file. If the value +includes a path and the path contains UI-culture-specific subdirectories, `Get-Help` searches the +subdirectories recursively for an XML file with the name of the script or function in accordance +with the language fallback standards established for Windows, just as it does in a module directory. For more information about the cmdlet help XML-based help file format, see [How to Write Cmdlet Help][01]. diff --git a/reference/docs-conceptual/developer/help/naming-help-files.md b/reference/docs-conceptual/developer/help/naming-help-files.md index 9985b29a0a56..2ae8800c6e5c 100644 --- a/reference/docs-conceptual/developer/help/naming-help-files.md +++ b/reference/docs-conceptual/developer/help/naming-help-files.md @@ -1,6 +1,6 @@ --- description: Naming Help files -ms.date: 07/10/2023 +ms.date: 09/22/2025 title: Naming Help files --- # Naming Help files @@ -49,11 +49,17 @@ There are no technical requirements for the name of a function help file. Howeve is to name the help file for the script module in which the function is defined. For example, the following function is defined in the `MyModule.psm1` file. -```csharp +```powershell #.EXTERNALHELP MyModule.psm1-help.xml function Test-Function { ... } ``` +Beginning in PowerShell 5.0, functions that are exported by a module can be documented in a help file +that is named for the module. You don't need to use `.EXTERNALHELP` comment keyword. For example, if +the `Test-Function` function is exported by the `MyModule` module, you can name the help file +`MyModule-help.xml`. The `Get-Help` cmdlet looks for help for the `Test-Function` function in the +`MyModule-help.xml` file in the module directory. + ## CIM Command Help files The help file for a CIM command must be named for the CDXML file in which the CIM command is diff --git a/reference/docs-conceptual/developer/help/writing-help-for-windows-powershell-modules.md b/reference/docs-conceptual/developer/help/writing-help-for-windows-powershell-modules.md index 32c6102f4a02..8a825f73b478 100644 --- a/reference/docs-conceptual/developer/help/writing-help-for-windows-powershell-modules.md +++ b/reference/docs-conceptual/developer/help/writing-help-for-windows-powershell-modules.md @@ -1,6 +1,6 @@ --- description: Writing Help for PowerShell Modules -ms.date: 07/10/2023 +ms.date: 09/22/2025 title: Writing Help for PowerShell Modules --- # Writing Help for PowerShell Modules @@ -17,47 +17,64 @@ guidelines for module Help content. A module can include the following types of Help. -- **Cmdlet Help**. The Help topics that describe cmdlets in a module are XML files that use the - command help schema - -- **Provider Help**. The Help topics that describe providers in a module are XML files that use the - provider help schema. - -- **Function Help**. The Help topics that describe functions in a module can be XML files that use - the command help schema or comment-based Help topics within the function, or the script or script - module - -- **Script Help**. The Help topics that describe scripts in a module can be XML files that use the - command help schema or comment-based Help topics in the script or script module. - -- **Conceptual ("About") Help**. You can use a conceptual ("about") Help topic to describe the - module and its members and to explain how the members can be used together to perform tasks. - Conceptual Help topics are text files with Unicode (UTF-8) encoding. The filename must use the - `about_.help.txt` format, such as `about_MyModule.help.txt`. By default, PowerShell includes - over 100 of these conceptual About Help topics, and they're formatted like the following example. - - ```Output - TOPIC - about_ - - SHORT DESCRIPTION - A short, one-line description of the topic contents. - - LONG DESCRIPTION - A detailed, full description of the subject or purpose of the module. - - EXAMPLES - Examples of how to use the module or how the subject feature works in practice. - - KEYWORDS - Terms or titles on which you might expect your users to search for the information in this topic. - - SEE ALSO - Text-only references for further reading. Hyperlinks can't work in the PowerShell console. - - ``` - -All the schema files can be found in the `$PSHOME\Schemas\PSMaml` folder. +- XML-based help + - **Cmdlet Help**. The Help topics that describe cmdlets in a module are XML files that use the + command help schema + - **Provider Help**. The Help topics that describe providers in a module are XML files that use + the provider help schema. + - **Function Help**. The Help topics that describe functions in a module can be XML files that use + the command help schema or comment-based Help topics within the function, or the script or + script module + - **Script Help**. The Help topics that describe scripts in a module can be XML files that use the + command help schema or comment-based Help topics in the script or script module. + - The `$PSHOME\Schemas\PSMaml` folder contains the schema files that define the XML format. + +- Conceptual ("About") help text files + + You can use a conceptual ("about") Help topic to describe the module and its members and to + explain how the members can be used together to perform tasks. By default, PowerShell includes + over 100 of these conceptual About Help topics. + + - Conceptual Help topics are text files with UTF-8 with BOM encoding. + - The filename must use the `about_.help.txt` format, such as `about_MyModule.help.txt`. + - For best display results, you should limit the length of each line to 80 characters. + - You can use the following sample template as a starting point for writing conceptual Help + topics. + + > [!NOTE] + > The `TOPIC` section header must start in the first column of the first line of the file. The + > section content on the second line should match the filename, without the `.help.txt` suffix. + > You must indent the content exactly 5 spaces. The third line must be blank. The + > `SHORT DESCRIPTION` section header must start in the first column of the fourth line. You must + > indent the content on the fifth line exactly 5 spaces. These requirements are necessary for + > the `Get-Help` cmdlet to recognize the content correctly. + + ``` + TOPIC + about_ + + SHORT DESCRIPTION + A short, one-line description of the topic contents. + + LONG DESCRIPTION + A detailed, full description of the subject or purpose of the module. + + EXAMPLES + Examples of how to use the module or how the subject feature works in + practice. + + KEYWORDS + Terms or titles on which you might expect your users to search for the + information in this topic. + + SEE ALSO + Text-only references for further reading. Hyperlinks can't work in the + PowerShell console. + ``` + + Except for the first two sections, the structure of conceptual Help topics is arbitrary. The + remaining section titles can be whatever is appropriate for your content. By convention, you + should use the same capitalization, indentation, and blank line separations. ## Placement of Module Help