nightroman/Helps

Format's bug in 'Out-Types' function

LaurentDardenne opened this issue · 8 comments

LaurentDardenne commented

Hi Roman,
for the 'inputs' and 'outputs' entries, the tag maml:description must be inside to the tag dev:type :

function Out-Types($HelpKey, $TagSet, $TagType, $Types) {
    "<$TagSet>"
    foreach($item in $Types) {
        Test-Hash $item $HelpKey $validTypeKeys

        "<$TagType>"

        '<dev:type>'
        $type = $item['type']
        if ($type) {
            "<maml:name>$(Encode-Xml $type)</maml:name>"
        }

        $description = @($item['description'])
        if ($description) {
            Out-Text maml:description maml:para $description
        }
        '</dev:type>'

        "</$TagType>"
    }
    "</$TagSet>"
}
nightroman commented

@LaurentDardenne, thank you for reporting this.

Hmm, yes and no. E.g. for Get-Random I can see:

<command:inputTypes>
    <command:inputType>
        <dev:type>
            <maml:name>System.Object</maml:name>
            <maml:uri></maml:uri>
            <maml:description>
            <maml:para />
            </maml:description>
        </dev:type>
        <maml:description>
            <maml:para>You can pipe one or more objects to Get-Random. Get-Random selects values randomly from the piped objects.</maml:para>
        </maml:description>
    </command:inputType>
</command:inputTypes>

I.e. description is both inside and outside. And the help text is actually written outside, just like Helps currently does.

What do you think? Does the current implementation cause issues? If yes then something has to be done, indeed. But if no then it makes sense to keep it as it is because it is not incorrect and it is like MS does.

LaurentDardenne commented

-"Does the current implementation cause issues?"
No.
But, when i am importing a XML file, (created with 'Helps') in CmdletHelpEditor(http://pscmdlethelpeditor.codeplex.com/) this tag is not imported.
Ok, for me it is not a bug, but a different interpretation.

Example with Helps :

<command:inputTypes>
  <command:inputType>
    <dev:type>
    </dev:type>
    <maml:description>
      <maml:para>System.Byte[], System.String, System.IO.DirectoryInfo, System.IO.FileInfo, Ionic.Zip.ZipEntry. You can send any object of the above types in the pipeline.</maml:para>
    </maml:description>
  </command:inputType>
</command:inputTypes>

Example with CmdletHelpEditor :

<command:inputTypes>
    <command:inputType>
        <dev:type>
            <maml:name></maml:name>
            <maml:uri/>
            <maml:description>
                <maml:para>System.Byte[], System.String, System.IO.DirectoryInfo, System.IO.FileInfo, Ionic.Zip.ZipEntry. You can send any object of the above types in the pipeline.</maml:para>
            </maml:description>
        </dev:type>
        <maml:description></maml:description>
    </command:inputType>
</command:inputTypes>

Example into Powershell help file (Fr-fr) :

 <command:inputTypes>
  <command:inputType>
    <dev:type>
      <maml:name>System.String</maml:name>
      <maml:uri>
      </maml:uri>
      <maml:description>
        <maml:para />
      </maml:description>
    </dev:type>
    <maml:description>
      <maml:para>Vous pouvez diriger les noms d’ordinateurs et les nouveaux noms vers l’applet de commande Add-Computer.</maml:para>
    </maml:description>
  </command:inputType>
</command:inputTypes>
nightroman commented

What do you propose to do? An option/parameter, perhaps? I do not mind to improve something but I am not sure what. The current implementation is MS-like and I would prefer to keep it this way.

A side note. Maybe you should report an issue to PowerShell Cmdlet Help Editor. Because on their side it definitely looks like a defect if they really do not import valid data.

Here is the official topic on MSDN. Helps follows it. A quote from there:

The schema includes two <maml:description> elements in each <command:inputType> element. However, the Get-Help cmdlet displays only the content of the <command:inputType>/<maml:description> element.

LaurentDardenne commented

-What do you propose to do? An option/parameter, perhaps?
No. I use a fork.
Thanks.

-Maybe you should report an issue to PowerShell Cmdlet Help Editor.
I should start by either one or the other.
I try this.

-Here is the official topic on MSDN. Helps follows.
I agree, but it is different here (http://blogs.msdn.com/b/powershell/archive/2006/09/14/draft-creating-cmdlet-help.aspx) :
8. In each command node, add a Command-InputTypes node

nightroman commented

The blog post is not documentation and it is very old (2006, i.e. PS v1.0). It hardly should be used as a reference now.

Anyway, it looks like we agree that no changes are needed so far in Helps. If this is correct I will close the issue.

If you submit a similar issue to PowerShell Cmdlet Help Editor, could you please add the link here? It may be useful.

LaurentDardenne commented

-It hardly should be used as a reference now.
May be, but i have not the XSD

-If this is correct I will close the issue.
Yes.

-It may be useful.
Yes, I think so too

Thanks Roman, sorry for the lost time.

nightroman commented

sorry for the lost time

No at all, it was a useful double check and we collected some relevant information.