search

red-gate / XmlDoc2CmdletDoc

Create cmdlet XML help files from XML doc comments
Other
64 stars 24 forks source link

Enum Array Parameters Do Not List Possible Values #42

Closed lordmilko closed 5 years ago

lordmilko commented 6 years ago

Potentially somewhat related to #33 , I've observed that when you have a parameter that takes an array of enums, the help text does not list all the possible values that are valid for the enum. I can see this text is generated by XmlDoc2CmdletDoc (and not dynamically determined by PowerShell) as the possible values for a parameter taking an array of enum are included in the resulting dll-Help.xml file

The following is generated for a parameter taking a single enum:

<command:parameter required="false" globbing="false" pipelineInput="false" position="named">
  <maml:name>Since</maml:name>
  <maml:description>
    <maml:para>Possible values: Today, Yesterday, LastWeek, LastMonth, LastSixMonths, LastYear, AllTime</maml:para>
  </maml:description>
  <command:parameterValue required="true">RecordAge</command:parameterValue>
  <dev:type>
    <maml:name>PrtgAPI.RecordAge</maml:name>
    <maml:uri />
  </dev:type>
  <command:parameterValueGroup>
    <command:parameterValue required="false" variableLength="false">Today</command:parameterValue>
    <command:parameterValue required="false" variableLength="false">Yesterday</command:parameterValue>
    <command:parameterValue required="false" variableLength="false">LastWeek</command:parameterValue>
    <command:parameterValue required="false" variableLength="false">LastMonth</command:parameterValue>
    <command:parameterValue required="false" variableLength="false">LastSixMonths</command:parameterValue>
    <command:parameterValue required="false" variableLength="false">LastYear</command:parameterValue>
    <command:parameterValue required="false" variableLength="false">AllTime</command:parameterValue>
  </command:parameterValueGroup>
</command:parameter>

And the following the output for an enum array

<command:parameter required="false" globbing="false" pipelineInput="true (ByValue)" position="named">
  <maml:name>Status</maml:name>
  <maml:description>
    <maml:para>Only retrieve objects that match a specific status.</maml:para>
  </maml:description>
  <command:parameterValue required="true">LogStatus[]</command:parameterValue>
  <dev:type>
    <maml:name>PrtgAPI.LogStatus[]</maml:name>
    <maml:uri />
  </dev:type>
</command:parameter>

In the array scenario the XmlDoc para description is used for the <maml:para>, whereas in the single value scenario the possible values are listed. I'm not sure whether or not this behavior is intentional, however from a usability perspective this prevents users from seeing the valid values that can be used with a parameter.

SimplySeb commented 6 years ago

100% agree, would love to see this feature