Parameter values in PowerShell HelpWriter.

Use this forum to ask questions after your subscription maintenance expires or before you buy. Need information on licensing or pricing? Questions about a trial version? This is the right place for you. No scripting questions, please.
Forum rules
DO NOT POST SUBSCRIPTION NUMBERS, LICENSE KEYS OR ANY OTHER LICENSING INFORMATION IN THIS FORUM.
Only the original author and our tech personnel can reply to a topic that is created in this forum. If you find a topic that relates to an issue you are having, please create a new topic and reference the other in your post.
This topic is 6 years and 5 months old and has exceeded the time allowed for comments. Please begin a new topic or use the search feature to find a similar but newer topic.
User avatar
WRARMSTRONG
Posts: 1
Last visit: Mon Oct 16, 2017 10:39 am

Parameter values in PowerShell HelpWriter.

Post by WRARMSTRONG »

Product, version and build: PowerShell HelpWriter 2017 Version 2.1.36
32 or 64 bit version of product: 64 bit
Operating system: Windows 10
32 or 64 bit OS: 64 bit

This is probably more product feedback than a technical question. If the product does have the options that I describe below, please let me know. Otherwise I'd like to suggest this as feedback, since the issues that I'm describing will probably prevent us from being able to use PowerShell HelpWriter.

PowerShell help XML schema has separate required attributes for parameter and parameterValue elements. This gives you the flexibility to specify the syntax of the parameter in these different ways:

-Param <value>
-Param [<value>]
[-Param <value>]
[-Param [<value>]]

The HelpWriter designer does not seem to have separate properties for parameter values vs. parameters. If you specify in the designer that a parameter is required, it sets the required attribute to true for BOTH the parameter and the parameter value. If you specify that a parameter is NOT required, it sets the required attribute to false for BOTH the parameter and the parameter value. This limits you to only these syntax combinations:

-Param <value>
[-Param [<value>]]

This is a problem because the second combination is actually seldom used. It means that if you do specify the parameter, you don't need to specify its value. Typically if you specify a parameter, its value is required. These are the most common combinations:

-Param <value>
[-Param <value>]

The designer really needs to offer separate properties for parameter values vs parameters.

Also, if the parameter is a switch parameter, you may want to document its syntax like this (with no value after the parameter name):

[-Param]

The normal way you do this is to not include a parameterValue element at all in the parameter element. The designer does not give you this option (as far as I can tell).

In our particular case, we're following the convention for switch parameters where we are excluding the parameterValue element in the syntax definition, but we are including it in the parameters collection. We feel that this gives you the clearest representation. It shows exactly how the parameter is used in the SYNTAX section, but gives you all of the parameter details in the PARAMETERS list.

For example, it would be displayed like so:

SYNTAX
New-Cmdlet [-Param]

PARAMETERS
-Param [<SwitchParameter>]

This representation is fairly common in Microsoft's PowerShell documentation. For example, see the -Force parameter for the cmdlet Get-Item.

I realize that you can accomplish all of this by editing the XML, but it is a pain to have to switch back and forth, especially since the editor doesn't keep the context when you do. For example if I'm editing a parameter for a particular cmdlet and I then switch to the XML editor, the cursor appears at the start of the XML file instead of the start of the parameter element that I was editing in the designer. The same is true when I switch back to the designer.
User avatar
davidc
Posts: 5913
Last visit: Mon Jul 08, 2019 8:55 am
Been upvoted: 2 times

Re: Parameter values in PowerShell HelpWriter.

Post by davidc »

We are investigating this and will update you as soon as we have more information. And thank you for the feedback. It is important to us and allows us to create better products.
David
SAPIEN Technologies, Inc.
This topic is 6 years and 5 months old and has exceeded the time allowed for comments. Please begin a new topic or use the search feature to find a similar but newer topic.