Multiple notes do not render as expected

[msorens]

Using this MAML from one of the acceptance tests...

<maml:alertSet xmlns:maml=""http://schemas.microsoft.com/maml/2004/10"">
  <maml:title>First Note</maml:title>
  <maml:alert>
    <maml:para>This is the description for the first note.</maml:para>
  </maml:alert>
  <maml:title>Second Note</maml:title>
  <maml:alert>
    <maml:para>This is part of the description for the second note.</maml:para>
    <maml:para>This is also part of the description for the second note.</maml:para>
  </maml:alert>
</maml:alertSet>";

... it is rendered in the output of Get-Help as this:

NOTES
    {First Note, Second Note}
        This is the description for the first note.
        This is part of the description for the second note.

        This is also part of the description for the second note.

Is that just how Get-Help does it or is there any way to tweak XmlDoc2CmdletDoc to get something closer to what it should be? Perhaps something like this...

NOTES
    {First Note}
        This is the description for the first note.

    {Second Note}
        This is part of the description for the second note.

        This is also part of the description for the second note.

[ChrisLambrou]

I remember looking into this at the time, and I think the basic problem is that the formatting of the Get-Help cmdlet just isn't very good. I've hit similar issues with it in the past, too. See #1, for example. 😞

[ChrisLambrou]

The current support for note looks like this:

/// <list type="alertSet">
///   <item>
///     <term>First note title</term>
///     <description>
///     This is the entire body text for the first note.
///     </description>
///   </item>
///   <item>
///     <term>Second note title</term>
///     <description>
///       <para>The first paragraph of the body text for the second note.</para>
///       <para>The second paragraph of the body text for the second note.</para>
///     </description>
///   </item>
/// </list>
[Cmdlet("Test", "MyExample")]
public class TestMyExampleCommand : Cmdlet
{
    ...
}

which would result in MAML in the format you've described above, as recommended here: https://msdn.microsoft.com/en-us/library/bb736330(v=vs.85).aspx

Get-Help is simply doing a poor job of rendering this, which I think leaves three options:

1. Do nothing. The work around is only write notes that don't look too bad when rendered by Get-Help. This probably means only having a single note, and maybe avoiding the note title entirely.
2. Get this tool to emit some other MAML. I'm a bit reluctant to do this, since we use other tools that also render cmdlet help, and they rely on the recommended MAML mark up.
3. Fix the Get-Help cmdlet.

Option 3 seems most attractive, since all PowerShell users would benefit from it. We could file a bug against it and see if Microsoft fix it, or crack open the code ourselves and submit a PR. It's code I'm not too familiar with, though, and I don't currently have much time to dig into it (perhaps I'll have a play with it over Christmas). That probably leaves us with option 1 for now, i.e. live with it.

[msorens]

Thanks, Chris. I considered the same set of possibilities and came to the same conclusion, your option 1, though I would word it as: use only a single note, with no title, and use paragraphs ( elements) within that note to emulate having multiple notes. If you review standard .NET cmdlets that seems to be just how they do it.

[ChrisLambrou]

Agreed! Will look into filing a bug with the Get-Help cmdlet, though.