Ensure empty descriptions notes, inputs, outputs and links create an accurate YAML (#720)

Author: adityapatwardhan

src/YamlWriter/CommandHelpYamlWriter.cs

@@ -211,7 +211,7 @@ internal override void WriteInputsOutputs(List<InputOutput> inputsoutputs, bool
                 }
                 else
                 {
-                    sb.AppendLine("  description:");
+                    sb.AppendLine("  description: ''");
                 }
             }
         }
@@ -226,7 +226,7 @@ internal override void WriteNotes(CommandHelp help)
 
             if (string.IsNullOrEmpty(help.Notes.Trim()))
             {
-                sb.AppendLine(Constants.NotesYamlHeader);
+                sb.AppendLine(Constants.NotesYamlHeader + " ''");
                 return;
             }
 
@@ -239,15 +239,20 @@ internal override void WriteNotes(CommandHelp help)
 
         internal override void WriteRelatedLinks(CommandHelp help)
         {
-            sb.AppendLine(Constants.RelatedLinksYamlHeader);
             if (help.RelatedLinks?.Count > 0)
             {
+                sb.AppendLine(Constants.RelatedLinksYamlHeader);
+
                 foreach (var link in help.RelatedLinks)
                 {
                     sb.AppendLine(string.Format("- text: '{0}'", link.LinkText));
                     sb.AppendLine(string.Format("  href: {0}", link.Uri));
                 }
             }
+            else
+            {
+                sb.AppendLine(Constants.RelatedLinksYamlHeader + " []");
+            }
         }
     }
 

test/Pester/MeasurePlatyPSMarkdown.Tests.ps1

@@ -13,10 +13,10 @@ Describe "Export-MarkdownModuleFile" {
 
     It "Should identify all the '<fileType>' assets" -TestCases @(
         @{ fileType = "unknown"; expectedCount = 2 }
-        @{ fileType = "CommandHelp"; expectedCount = 34 }
+        @{ fileType = "CommandHelp"; expectedCount = 35 }
         @{ fileType = "ModuleFile"; expectedCount = 14 }
         @{ fileType = "V1Schema"; expectedCount = 45 }
-        @{ fileType = "V2Schema"; expectedCount = 3 }
+        @{ fileType = "V2Schema"; expectedCount = 4 }
     ) {
         param ($fileType, $expectedCount)
         $idents.Where({($_.FileType -band $fileType) -eq $fileType}).Count | Should -Be $expectedCount

test/Pester/YamlFormatting.Tests.ps1

@@ -0,0 +1,21 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+Describe 'Yaml formatting tests' {
+    It 'Inputs output and notes should have empty array when empty' {
+        Import-MarkdownCommandHelp -Path 'assets/New-EmptyCommand.md' | Export-YamlCommandHelp -OutputFolder $TestDrive
+        $yaml = Get-Content "$TestDrive/New-EmptyCommand.yml" -Raw
+
+        $isWinPS = $PSVersionTable.PSVersion.Major -eq 5
+
+        $inputPattern = if ($IsWindows -or $IsWinPS) { 'inputs:\r\n- name: System\.String\r\n  description: ''' } else { 'inputs:\n- name: System\.String\n  description: ''' }
+        $outputPattern = if ($IsWindows -or $IsWinPS) { 'outputs:\r\n- name: System\.String\r\n  description: ''' } else { 'outputs:\n- name: System\.String\n  description: ''' }
+        $notesPattern = "notes: ''"
+        $linksPattern = "links: \[\]"
+
+        $yaml | Should -Match $inputPattern
+        $yaml | Should -Match $outputPattern
+        $yaml | Should -Match $notesPattern
+        $yaml | Should -Match $linksPattern
+    }
+}

test/Pester/assets/New-EmptyCommand.md

@@ -0,0 +1,84 @@
+---
+document type: cmdlet
+external help file: New-EmptyCommand-Help.xml
+HelpUri: ''
+Locale: en-US
+Module Name: ''
+ms.date: 03/04/2025
+PlatyPS schema version: 2024-05-01
+title: New-EmptyCommand
+---
+
+# New-EmptyCommand
+
+## SYNOPSIS
+
+{{ Fill in the Synopsis }}
+
+## SYNTAX
+
+### __AllParameterSets
+
+```
+New-EmptyCommand [[-InputString] <string>] [<CommonParameters>]
+```
+
+## ALIASES
+
+This cmdlet has the following aliases,
+  {{Insert list of aliases}}
+
+## DESCRIPTION
+
+{{ Fill in the Description }}
+
+## EXAMPLES
+
+### Example 1
+
+{{ Add example description here }}
+
+## PARAMETERS
+
+### -InputString
+
+{{ Fill InputString Description }}
+
+```yaml
+Type: System.String
+DefaultValue: ''
+SupportsWildcards: false
+ParameterValue: []
+Aliases:
+- InputObject
+- InputParameter
+ParameterSets:
+- Name: (All)
+  Position: 0
+  IsRequired: false
+  ValueFromPipeline: true
+  ValueFromPipelineByPropertyName: false
+  ValueFromRemainingArguments: false
+DontShow: false
+AcceptedValues: []
+HelpMessage: ''
+```
+
+### CommonParameters
+
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
+-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable,
+-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see
+[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+### System.String
+
+## OUTPUTS
+
+### System.String
+
+## NOTES
+
+## RELATED LINKS