[UPDATE 2014-12-01] An update to this issue. It seem that this only appears PowerShell v3 and not in PowerShell v4 any more.

When we create our Cmdlets we often supply a link to an Internet resource where we can put updated or more extensive help information. We normally do this in addition to providing some inline help in the Cmdlets. And with PoewrShell this is pretty simple to do, you only have to specify the “HelpURI” attribute in the “CmdletBinding” section and place some “” comment block with keywords like “.SYNOPSIS” in the header of your function.

But today I realized that in order to have the HelpURI attribute actually working, you MUST specify the “.HELPURI” keyword in the “” comment block as well – even without specifying any link at all.

This is rather strange. And what is even stranger, this does not happen with script functions that you dot-source but only with script files that you define as NestedModules (in separate PS1 files) in your PowerShell module. So here a two nearly identical Cmdlets defined in separate PS1 files that are imported into a module. The first “My-CmdletWithWorkingHelpUri.ps1” can display a HelpURI as is also has the “.HELPURI” in the comment section:

function My-CmdletWithWorkingHelpUri {
<#

.SYNOPSIS

This is a Cmdlet with inline help and a working HelpURI.

.HELPURI
#>
[CmdletBinding(
  HelpURI='http://d-fens.ch'
)]
PARAM 
(
  # Specify if the online help uri should be called upon invoking the script
  [Parameter(Mandatory = $false, Position = 0)]
  [switch] $OpenHelpUri = $false
)

[string] $fn = $MyInvocation.MyCommand.Name;
$Command = (Get-Command $MyInvocation.MyCommand);
$HelpUri = $Command.HelpUri;
Write-Host ("HelpUri of '{0}' is '{1}'" -f $fn, $HelpUri)

if($OpenHelpUri -And $HelpUri)
{
  Write-Host ("Havigating to HelpUri '{0}' ..." -f $HelpUri);
  (New-Object -Com Shell.Application).Open($HelpURI)
}

} # function

This one does not display a HelpURI though it also has the HelpURI attribute correctly defined:

function My-CmdletWithoutWorkingHelpUri {
<#

.SYNOPSIS

This is a Cmdlet with inline help and NO working HelpURI.
#>
[CmdletBinding(
  HelpURI='http://d-fens.ch'
)]
PARAM 
(
  # Specify if the online help uri should be called upon invoking the script
  [Parameter(Mandatory = $false, Position = 0)]
  [switch] $OpenHelpUri = $false
)

[string] $fn = $MyInvocation.MyCommand.Name;
$Command = (Get-Command $MyInvocation.MyCommand);
$HelpUri = $Command.HelpUri;
Write-Host ("HelpUri of '{0}' is '{1}'" -f $fn, $HelpUri)

if($OpenHelpUri -And $HelpUri)
{
  Write-Host ("Havigating to HelpUri '{0}' ..." -f $HelpUri);
  (New-Object -Com Shell.Application).Open($HelpURI)
}

} # function

If this is a bug or a feature I do not know, but it certainly is not really straightforward. I observed this behaviour with Powershell v3.

As a side note: When using Allman coding style you have to make sure that the opening bracket in the “function” keyword is NOT put on a separate line (but on the same line as the function keyword), otherwise the inline help will not be displayed (see first line of examples)!

[UPDATE 2014-12-01] Another issue with the inline help is the treatment of the comment blocks above the function’s parameter definitions. If you define them inline as with the examples above you will see the commented text as the description of the parameters when you call ‘Get-Help My-CmdletWithoutWorkingHelpUri -full’. However when you omit the comment block below the ‘function’ keyword the comments will not be treated as inline help parameter descriptions.

function My-CmdletWithoutWorkingHelpUri {
[CmdletBinding(
  HelpURI='http://d-fens.ch'
)]
PARAM 
(
  # This comment is not recognised as a parameter description as there is no above comment block
  [Parameter(Mandatory = $false, Position = 0)]
  [switch] $OpenHelpUri = $false
)

[string] $fn = $MyInvocation.MyCommand.Name;
$Command = (Get-Command $MyInvocation.MyCommand);
$HelpUri = $Command.HelpUri;
Write-Host ("HelpUri of '{0}' is '{1}'" -f $fn, $HelpUri)

if($OpenHelpUri -And $HelpUri)
{
  Write-Host ("Havigating to HelpUri '{0}' ..." -f $HelpUri);
  (New-Object -Com Shell.Application).Open($HelpURI)
}

} # function