Update docs on comment-based help (#12375)

Author: sdwheeler

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
-<ScriptModule.psm1>-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

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
-<ScriptModule.psm1>-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

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
-<ScriptModule.psm1>-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

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
-<ScriptModule.psm1>-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

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,105 +20,96 @@ 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 <Parameter-Name>`
 
-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`
 
 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 <Command-Name>`
 
-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 <Command-Name>
 ```
 
 ## `.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 <Category>
 ```
 
 ## `.REMOTEHELPRUNSPACE <PSSession-variable>`
 
-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 <PSSession-variable>
@@ -132,31 +123,26 @@ Specifies an XML-based help file for the script or function.
 # .EXTERNALHELP <XML Help File>
 ```
 
-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
-<ScriptModule.psm1>-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].

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