Writing XML-Based Help Topics for Scripts and Functions

 

This topic explains how to write an XML-based help topic for a function or script.

Create the XML File

To create an XML-based help topic for a function or script, follow the instructions that are provided in the Writing XML-Based Help Topics for Commands topic. You can include multiple help topics in each XML-based file.

To enable the T:Microsoft.PowerShell.Commands.Get-Help cmdlet to find the XML-based help file for a function or script, add the ExternalHelp comment keyword to the function or script. The value of the ExternalHelp keyword is the path and/or name of the XML-based help file. The ExternalHelp keyword is required. Without it, Get-Help cannot find the help file. For more information about the ExternalHelp keyword, see about_Comment_Based_Help [v4] and Writing Comment-Based Help Topics.

When the ExternalHelp keyword is present, it takes precedence over other comment-based help keywords. Get-Help does not display comment-based help, even if it cannot find a help file that matches the value of the ExternalHelp keyword.

You can use any name for the XML file, but to simplify distribution and management, give the XML file the same name as the script or function that it documents, but with an .xml file name extension. The XML-based help file for the functions that are exported by a script module should have the following format: <ScriptModule>.psm1-help.xml.

In a script help topic, when specifying the command name in the Command:Name Element (Command XML) element and the Maml:Name Element for Command:SyntaxItem (Command XML), enter the full name of the script file, including the .ps1 file name extension. This makes the syntax accurate and matches what users must type at the command line to invoke the script. For functions, enter the function name, just as you would for a cmdlet.

For example, the following XML for the New-Topic.ps1 script help topic shows the elements that contain the command name.

<?xml version="1.0" encoding="utf-8" ?>
<helpItems schema="maml">
<command:command xmlns:maml="https://schemas.microsoft.com/maml/2004/10" xmlns:command="https://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="https://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
    <command:name>
        New-Topic.ps1
    </command:name>
...
<command:syntax>
    <command:syntaxItem>
        <maml:name>New-Topic.ps1</maml:name>
...

In the detailed description, explain that the command is a script or function. This information is particularly useful to users when the session includes multiple commands with the same name, some of which might be hidden by a command with higher precedence.

For example, the following detailed description states that the New-Topic command is a script. This reminds users that they need to specify the path and full name when they run it.

<maml:description>
    <maml:para>The New-Topic script creates a blank conceptual topic for each topic name in the input file...</maml:para>
</maml:description>

The following detailed description states that Disable-PSRemoting is a function.

<maml:description>
    <maml:para>The Disable-PSRemoting function disables all session configurations on the local computer by adding a &quot;deny all&quot; entry to their security descriptors. This prevents the local computer from receiving remote commands...
</maml:description>

Add the .ExternalHelp Keyword

Add the .ExternalHelp comment keyword to the script or function followed by the path and name of the XML file that contains the help topic.

Distributing the Help Topic