New-ExternalHelp is not including all remarks for an example

[sdwheeler]

The problem

The current platyps schema for Examples allows the following:

## Examples

### Example 1

0 or more paragraphs
1 or more code blocks
0 or more paragraphs

When the markdown is converted to MAML, only the paragraphs after the code blocks are written to the MAML file.

The problem is that most of our help content has been updated to use the pattern shown above.

Example case

I have the following example in markdown.

### EXAMPLE 3 - Run only the DSC rules with the Error severity

This example runs only the DSC rules with the Error severity on the files in the **MyDSCModule**
module.

```powershell
$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where-Object SourceName -eq PSDSC
$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule\*"
Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse
```

Using the **IncludeRule** parameter of `Invoke-ScriptAnalyzerRule` is more efficient than using its
**Severity** parameter, which is applied only after using all rules to analyze all module files.

The MAML that is produced contains:

      <command:example>
        <maml:title>-- EXAMPLE 3 - Run only the DSC rules with the Error severity --</maml:title>
        <dev:code>$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where-Object SourceName -eq PSDSC
$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule\*"
Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse</dev:code>
        <dev:remarks>
          <maml:para>Using the IncludeRule parameter of `Invoke-ScriptAnalyzerRule` is more efficient than using its Severity parameter, which is applied only after using all rules to analyze all module files.</maml:para>
        </dev:remarks>
      </command:example>

Notice that the <dev:remarks> element only contains the paragraph after the code block.

Suggested fix

New-ExternalHelp should create a <dev:remarks> element for every paragraph in the example. Inside the <command:example> element the <dev:remarks> and <dev:code> elements should be ordered as written in the markdown.

Proof of concept

I edited the MAML file to add the missing paragraph:

      <command:example>
        <maml:title>-- EXAMPLE 3 - Run only the DSC rules with the Error severity --</maml:title>
        <dev:remarks><maml:para>This example runs only the DSC rules with the Error severity on the files in the **MyDSCModule** module.</maml:para></dev:remarks>
        <dev:code>$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where-Object SourceName -eq PSDSC
$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule\*"
Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse</dev:code>
        <dev:remarks>
          <maml:para>Using the IncludeRule parameter of `Invoke-ScriptAnalyzerRule` is more efficient than using its Severity parameter, which is applied only after using all rules to analyze all module files.</maml:para>
        </dev:remarks>
      </command:example>

Now Get-Help displays both remarks (though not in the written order).

PS C:\Git> (Get-Help -full Get-ScriptAnalyzerRule).examples.example[2]

-- EXAMPLE 3 - Run only the DSC rules with the Error severity --

$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where-Object SourceName -eq PSDSC
$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule\*"
Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse


This example runs only the DSC rules with the Error severity on the files in the **MyDSCModule** module.
Using the IncludeRule parameter of `Invoke-ScriptAnalyzerRule` is more efficient than using its Severity parameter,
which is applied only after using all rules to analyze all module files.

Get-Help and the HelpInfo object model need to support this better.