Powershell: Get-Help with function script should return help of all functions in the script

[asears]

Summary of the new feature/enhancement

By default, a script which only contains functions with their help does not display any output when using

Get-Help .\myscript.ps1

This behavior also happens if the parameters or syntax of the synopsis is incorrect.

Proposed technical implementation details (optional)

Display the list of functions within the script with their help, or some meaningful information from the script, instead of empty result.

An option to validate the synopsis of the script and each function's synopsis, or warn on synopsis errors would be helpful.

[kvprasoon]

Not sure, Get-Help is intended to show help for PowerShell concepts and commands, including cmdlets, functions, CIM
commands, workflows, providers, aliases and scripts. It accepts one item and AFAIK, doesn't expect passing a library of functions defined in a file.

[vexx32]

Generally speaking, if you want help included with the script, you'd need to add a comment-based help block to the script itself. So this is to some extent already doable. Part of the reason perhaps that PS doesn't scan entire scripts for _function_ help blocks is that the function itself doesn't exist in the PS session unless you dot source the script.

It won't do that automatically, because there's no way to tell if running that script in order to import the functions may have side effects.

I get the impression that if you need the help data to be available in the PS session, you should probably be packaging the script as or with a module containing those functions. A script that has some functions _and_ also does some other things creates a bit of a catch-22, where the user and the PS engine can't really query the functions directly without also invoking the rest of the code in the script. And you can't really use the AST to find the function blocks and parse their help individually either; comments don't exist in the AST, they only exist as tokens.

My general feeling is that this use case is uncommon and would be much easier to manage as a module, and help would "just work" if that were the case.

[asears]

That makes sense to me, thanks. I wonder if get-help could just stupidly parse the text of the file as a fallback? Probably internal issue there.

It would help to have some synopsis validation tool though, rather than silent failure.

An example here would be

<# 
.SYNOPSIS 
my script
.PARAMETER
does not work
#>
[CmdletBinding()]
param()
#>

I have synopsis, so I would expect it would pick that up then throw warning or exception about syntax, rather than ignore this case altogether.

I found that PlatyPS picked up this particular issue for me using New-MarkdownHelp - with another unhelpful error.
Will close this issue and leave the rest up to using templates for help.