In what situations is `.AHPARAMETER` expected to do anything?

[jimbobmcgee]

I've been trying to get working some of the behaviours described in Augmented Help, so that Otter might generate rudimentary input UI for my ad-hoc scripts. However, I must be reading it wrong, because nothing I seem to do with these makes any difference.

Consider the rudimentary OtterScript...

/*  .AHPARAMETERS
    .AHPARAMETER TestA(input, text)
    This is a simple test input

    .AHPARAMETER TestB(input, list, values='optA,optB' default='optA')
    This is another test input, with allowed values limited to specific items

    .AHPARAMETER TestC(input, text, sensitive)
    This is a third test input, which might render as a password field
*/
Log-Information "A test -- this is unimportant";

...or a similar rudimentary PowerShell...

<#
.AHPARAMETER TestA(input, text)
.AHPARAMETER TestB(input, list, values='optA,optB' default='optA')
.AHPARAMETER TestC(input, text, sensitive)
#>
Param(
    [String]  $TestA,
    [String]  $TestB,
    [String]  $TestC,
    [Switch]  $TestD
)
Write-Output "A test -- this is unimportant"

When creating an ad-hoc job to run these (i.e. from the button in the list within the Scripts screen), I anticipate that input fields should be shown for $Test1, $Test2, $Test3, etc., with certain special attributes applied.

However...

1. the PowerShell ad-hoc job shows the input parameters derived from the Param block (including a checkbox for $TestD), but does not present a list for $TestB, nor does it mask the sensitive $TestC.
2. the OtterScript ad-hoc job never shows any input parameters at all.

The only way I can get input parameters to show reliably is to create an associated Job Template and define them there (using the Job Template GUI or directly in the Raft JSON), but that obviously requires keeping two different parameter sets in sync (i.e. the one in the script and the one in the template); and these never apply to an ad-hoc script execution.

The implication in the documentation is that Augmented Help is designed to keep this in one place, and is the preferred way to apply these attributes.

What am I missing here? What is the "right" way to document my parameters such that the UI might pick it up?

---

Some more-targeted stuff I've tried

(this may or may not be relevant...)

A cursory scan of the decompiled PowerShellScriptParameterInfo.Parse(...) from Scripting.dll suggests that the pattern used to extract values from a comment-based help block only picks these up if they are in the form...

.AHPARAMETER TestC
input, text, sensitive

(i.e. not .AHPARAMETER TestC(input, text, sensitive) as in the documentation.) I've tried this form, both with and without the surrounding brackets, but it makes no difference.

The same decompilation does not refer to AHPARAMETER in the code, although AHEXECMODE, SYNOPSIS, DESCRIPTION and PARAMETER are referenced.

The nearest equivalent I can find for OtterScript may be in the decompilation of OtterScriptLanguage in OtterCoreEx.dll, which has methods GetParameters(...) and ParseScriptInfo(...). Neither of these seem to mention AHPARAMETER either (although the former has a check for if (!additionalHeader.StartsWith("Parameter")) {...}. I can't follow it back far enough to see how additionalHeader is populated though.

I can see in similar decompilations that the script engines for Batch, Shell and Python seem to favour # AhParameters (plural) or # AhArgFormat -- I've tried similar strings in my OtterScript and PowerShell scripts (e.g. .AHPARAMETERS and .AHARGFORMAT).

I note very similar documentation for BuildMaster (2,3) as well, but I haven't got one of those in place with which to test.