Powershell HelpWriter doesn't read all info from a Powershell module

[Juha Metsäkallas]

Product, version and build: PowerShell HelpWriter 2020, v 2.3.47.0
Operating system: MS Windows Server 2019 Datacenter
PowerShell version(s): 5.1.17763.1007
32-bit version of software? No, 64 bit.

Hello!

I have a Powershell file runme ps1 which reads a configuration file (an ini) and then calls several functions in a Powershell module myModule. This module utilises a couple of auxiliary modules to do its work. This system works between two Sharepoint servers by reading items in a source document library on a server where the scripts are (using the built-in Powershell Sharepoint module), process them and writing the results into a target document library on another server (using the Sharepoint PnP module).

The idea is that the runme script file will be scheduled to run once every night. All this works, i.e. the script is scheduled and already in production. What remains is to document the system.

For that purpose all custom modules have comment blocks with SYNOPSIS, PARAMETER, DESCRIPTION and so on for every function. What I need to do, is to extract those comment infos and have documentation over all functions to be handed over to the customer.

But I've stumbled on a couple of issues.

1. It seems that I must run PowerShell HelpWriter on the source Sharepoint server and not e.g. on my desktop computer (which isn't a Sharepoint servers). I can do this on a development server.

2. If I select "New Help Project (From Module)", I must browse to the source files as they are not registered into the runtime environment. I can do this.

3. The help file, myModule.psm1-Help.xml, will be only partially populated. While it seems to contain all functions, the help files don't contain synopsises or descriptions for my functions. Is there a more specific document how I should have my comments for the auto-generation to work?

4. …but they contain those for functions in PowerShell Sharepoint and Sharepoint PnP, which I don't need at all. I don't know how to not have them generated.

[brittneyr]

We are currently investigating this behavior. We have had no issues getting the synopses and descriptions for functions from modules that are locally or from a network.

The comments need to be in the following format:

Code: Select all

<#
	.SYNOPSIS
		This is a test function.
	
	.DESCRIPTION
		This is a test to see if what information helpwriter reads in when generating help from an existing module.
	
	.PARAMETER tester
		This is a test paramerter.
	
	.PARAMETER working
		Is this working?
	
	.EXAMPLE
		Test-HelpWriter -tester 'Value1'
	
	.NOTES
		Additional information about the function.
#>

If the module has updated since you initially created the help project, then you might need to refresh the help:

PHW_RefreshHelp.png (18.42 KiB) Viewed 2692 times

Also, when creating a new project and using existing module information, you need to have the following checked:

PHW_IncludeExistingHelp.png (36.8 KiB) Viewed 2692 times

[Juha Metsäkallas]

Thank you for your answer,

I rechecked those settings, but I still fail to see what causes this issue. I've attached a very short example module with

• module intro as a comment block

• two functions with comment blocks

• export declarations

Powershell HelpWriter reads the comment block for the function ConvertTo-EncryptedPassword correctly, but does not generate synopsis nor descriptions (for anything) for the function Get-CredentialFromFile.

AcmePasswords.txt

(2.25 KiB) Downloaded 464 times

[brittneyr]

Please try moving your comment blocks to above the functions blocks and try rebuilding again. Like so:

<#
.SYNOPSIS
Returns a PSCredential object with given user name and password.

.PARAMETER username
The user name in plain text.

.PARAMETER passwordFilename
The full path to an encrypted password file (default = ".\securepassword.txt".

.OUTPUT
A PSCredential object

.DESCRIPTION
The function returns a PSCredential object of the given user name and the content of the give password file.

.EXAMPLE
Get-Credentials -username "AD\foobar" -passwordFilename ".\mypassword.txt"
#>
function Get-CredentialFromFile
{
param
(
[parameter(mandatory)][string]$username,
[string]$passwordFilename = ".\securepassword.txt"
)

$fileContent = Get-Content -path $passwordFilename
$password = ConvertTo-SecureString -string $fileContent
New-Object -typename System.Management.Automation.PSCredential -argumentlist $username,$password

} # Get-CredentialFromFile

[Juha Metsäkallas]

Please try moving your comment blocks to above the functions blocks and try rebuilding again

I removed the initial comment block and moved the function comment blocks above the functions. I changed all tabs to spaces but in vain. I tried both by rebuilding and by totally buildng from strach. The result is the same, I still have the synopsis and description only for the first function in that Acme module, not for the second.

[brittneyr]

I believe I found the issue. After testing this with PowerShell Studio and its function builder, I found the problem to be .OUTPUT should be .OUTPUTS. After updating this, all the help information was present in HelpWriter. When I was previously testing this, I was running your functions through the function builder to verify that it was able to read all of your functions information correctly which automatically moves the help comment to be above the function. After further testing with PowerShell HelpWriter, it should does not matter where the help comment is (above or inside).

My apologies for the confusion. Please let me know if this works for you after updating your comment and refreshing your PowerShell HelpWriter project.

[Juha Metsäkallas]

Hey, changing OUTPUT to OUTPUTS helped! Thank you! I checked MS's documentation quide lines and indeed its INPUTS and OUTPUTS, which is strange since all other keywords are in singular.

Okey, now remains the last item

4. …but they contain those for functions in PowerShell Sharepoint and Sharepoint PnP, which I don't need at all. I don't know how to not have them generated.

i.e. my documentation project contains tens of entries for functions from Sharepoint and PnP modules. I don't need them. How do I remove them in one sweep (and not one by one because shift selecting them doesn't work) or even better prevent generating them in the first place?

Edit:
Ha, they don't come into the generated HTML or markdown file. Good, problem solved.