From f1ace489a7c2fe57ba3cfc72bcdd4dced5eb5a1b Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Mon, 30 Jun 2025 16:43:03 -0700 Subject: [PATCH 1/4] Ensure the next header after description is examples while parsing MD --- src/MarkdownReader/CommandHelpMarkdownReader.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/MarkdownReader/CommandHelpMarkdownReader.cs b/src/MarkdownReader/CommandHelpMarkdownReader.cs index b6433bdd..bc8a7daa 100644 --- a/src/MarkdownReader/CommandHelpMarkdownReader.cs +++ b/src/MarkdownReader/CommandHelpMarkdownReader.cs @@ -561,7 +561,7 @@ internal static string GetDescriptionFromMarkdown(ParsedMarkdownContent markdown diagnostics.Add(new DiagnosticMessage( DiagnosticMessageSource.Description, "DESCRIPTION header found", DiagnosticSeverity.Information, "DESCRIPTION", markdownContent.GetTextLine(start))); markdownContent.Seek(start); markdownContent.Take(); - var end = markdownContent.FindHeader(2, string.Empty); + var end = markdownContent.FindHeader(2, "EXAMPLES"); return markdownContent.GetStringFromAst(end).Trim(); } From 60b3df31fbed9fa9852a8fb85a521ba628ee04df Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Mon, 30 Jun 2025 16:57:54 -0700 Subject: [PATCH 2/4] Add tests --- .../ImportMarkdownCommandHelp.Tests.ps1 | 10 +++ test/Pester/assets/Compare-CommandHelp.md | 69 +++++-------------- 2 files changed, 29 insertions(+), 50 deletions(-) diff --git a/test/Pester/ImportMarkdownCommandHelp.Tests.ps1 b/test/Pester/ImportMarkdownCommandHelp.Tests.ps1 index b1c67028..3ac3a2d9 100644 --- a/test/Pester/ImportMarkdownCommandHelp.Tests.ps1 +++ b/test/Pester/ImportMarkdownCommandHelp.Tests.ps1 @@ -251,4 +251,14 @@ Describe 'Import-MarkdownCommandHelp Tests' { $ch.Syntax[$offset].ToString() | Should -Be $string } } + + Context 'Validate Description' { + BeforeAll { + $ch = Import-MarkdownCommandHelp "$PSScriptRoot/assets/Compare-CommandHelp.md" + } + + It "Should handle empty description" { + $ch.Description | Should -BeNullOrEmpty + } + } } diff --git a/test/Pester/assets/Compare-CommandHelp.md b/test/Pester/assets/Compare-CommandHelp.md index ccf3e622..c3927229 100644 --- a/test/Pester/assets/Compare-CommandHelp.md +++ b/test/Pester/assets/Compare-CommandHelp.md @@ -1,66 +1,45 @@ --- document type: cmdlet -title: Compare-CommandHelp +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -Locale: "en-US" +ms.date: 03/07/2025 PlatyPS schema version: 2024-05-01 -HelpUri: -ms.date: 05/20/2024 -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +title: Compare-CommandHelp --- # Compare-CommandHelp ## SYNOPSIS -{{ Fill in the Synopsis }} - ## SYNTAX ### __AllParameterSets ``` -Compare-CommandHelp [-Reference] [-Difference] - [-PropertyNamesToExclude ] [] +Compare-CommandHelp [-ReferenceCommandHelp] [-DifferenceCommandHelp] + [-PropertyNamesToExclude ] [] ``` ## ALIASES This cmdlet has the following aliases, - {{Insert list of aliases}} ## DESCRIPTION -{{ Fill in the Description }} - ## EXAMPLES -### My Example - -description - -```powershell -PS> write-output hi -hi -``` - -description 2 - -```powershell -PS> echo bye -bye -``` - -description 3 +### Example 1 ## PARAMETERS -### -Difference +### -DifferenceCommandHelp ```yaml -Type: CommandHelp +Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp DefaultValue: '' -Globbing: false +SupportsWildcards: false ParameterValue: [] Aliases: [] ParameterSets: @@ -77,12 +56,10 @@ HelpMessage: '' ### -PropertyNamesToExclude -{{ Fill PropertyNamesToExclude Description }} - ```yaml -Type: String[] +Type: System.String[] DefaultValue: '' -Globbing: false +SupportsWildcards: false ParameterValue: [] Aliases: [] ParameterSets: @@ -97,14 +74,12 @@ AcceptedValues: [] HelpMessage: '' ``` -### -Reference - -{{ Fill Reference Description }} +### -ReferenceCommandHelp ```yaml -Type: CommandHelp +Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp DefaultValue: '' -Globbing: false +SupportsWildcards: false ParameterValue: [] Aliases: [] ParameterSets: @@ -123,23 +98,17 @@ HelpMessage: '' This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, -WarningVariable. -For more information, see +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS -### System.Management.Automation.HiThere +### Microsoft.PowerShell.PlatyPS.Model.CommandHelp ## OUTPUTS -### System.Object +### System.String ## NOTES -Just a note - ## RELATED LINKS - - - From cf2e3379c0f25e72b62b632bee40e9b7d1b7961e Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Tue, 1 Jul 2025 10:39:22 -0700 Subject: [PATCH 3/4] Add new test file --- .../ImportMarkdownCommandHelp.Tests.ps1 | 2 +- test/Pester/assets/Compare-CommandHelp.md | 69 ++++++++--- test/Pester/assets/Compare-CommandHelp2.md | 114 ++++++++++++++++++ 3 files changed, 165 insertions(+), 20 deletions(-) create mode 100644 test/Pester/assets/Compare-CommandHelp2.md diff --git a/test/Pester/ImportMarkdownCommandHelp.Tests.ps1 b/test/Pester/ImportMarkdownCommandHelp.Tests.ps1 index 3ac3a2d9..c1028836 100644 --- a/test/Pester/ImportMarkdownCommandHelp.Tests.ps1 +++ b/test/Pester/ImportMarkdownCommandHelp.Tests.ps1 @@ -254,7 +254,7 @@ Describe 'Import-MarkdownCommandHelp Tests' { Context 'Validate Description' { BeforeAll { - $ch = Import-MarkdownCommandHelp "$PSScriptRoot/assets/Compare-CommandHelp.md" + $ch = Import-MarkdownCommandHelp "$PSScriptRoot/assets/Compare-CommandHelp2.md" } It "Should handle empty description" { diff --git a/test/Pester/assets/Compare-CommandHelp.md b/test/Pester/assets/Compare-CommandHelp.md index c3927229..ccf3e622 100644 --- a/test/Pester/assets/Compare-CommandHelp.md +++ b/test/Pester/assets/Compare-CommandHelp.md @@ -1,45 +1,66 @@ --- document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US +title: Compare-CommandHelp Module Name: Microsoft.PowerShell.PlatyPS -ms.date: 03/07/2025 +Locale: "en-US" PlatyPS schema version: 2024-05-01 -title: Compare-CommandHelp +HelpUri: +ms.date: 05/20/2024 +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml --- # Compare-CommandHelp ## SYNOPSIS +{{ Fill in the Synopsis }} + ## SYNTAX ### __AllParameterSets ``` -Compare-CommandHelp [-ReferenceCommandHelp] [-DifferenceCommandHelp] - [-PropertyNamesToExclude ] [] +Compare-CommandHelp [-Reference] [-Difference] + [-PropertyNamesToExclude ] [] ``` ## ALIASES This cmdlet has the following aliases, + {{Insert list of aliases}} ## DESCRIPTION +{{ Fill in the Description }} + ## EXAMPLES -### Example 1 +### My Example + +description + +```powershell +PS> write-output hi +hi +``` + +description 2 + +```powershell +PS> echo bye +bye +``` + +description 3 ## PARAMETERS -### -DifferenceCommandHelp +### -Difference ```yaml -Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp +Type: CommandHelp DefaultValue: '' -SupportsWildcards: false +Globbing: false ParameterValue: [] Aliases: [] ParameterSets: @@ -56,10 +77,12 @@ HelpMessage: '' ### -PropertyNamesToExclude +{{ Fill PropertyNamesToExclude Description }} + ```yaml -Type: System.String[] +Type: String[] DefaultValue: '' -SupportsWildcards: false +Globbing: false ParameterValue: [] Aliases: [] ParameterSets: @@ -74,12 +97,14 @@ AcceptedValues: [] HelpMessage: '' ``` -### -ReferenceCommandHelp +### -Reference + +{{ Fill Reference Description }} ```yaml -Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp +Type: CommandHelp DefaultValue: '' -SupportsWildcards: false +Globbing: false ParameterValue: [] Aliases: [] ParameterSets: @@ -98,17 +123,23 @@ HelpMessage: '' This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +-ProgressAction, -Verbose, -WarningAction, -WarningVariable. +For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS -### Microsoft.PowerShell.PlatyPS.Model.CommandHelp +### System.Management.Automation.HiThere ## OUTPUTS -### System.String +### System.Object ## NOTES +Just a note + ## RELATED LINKS + + + diff --git a/test/Pester/assets/Compare-CommandHelp2.md b/test/Pester/assets/Compare-CommandHelp2.md new file mode 100644 index 00000000..c3927229 --- /dev/null +++ b/test/Pester/assets/Compare-CommandHelp2.md @@ -0,0 +1,114 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.date: 03/07/2025 +PlatyPS schema version: 2024-05-01 +title: Compare-CommandHelp +--- + +# Compare-CommandHelp + +## SYNOPSIS + +## SYNTAX + +### __AllParameterSets + +``` +Compare-CommandHelp [-ReferenceCommandHelp] [-DifferenceCommandHelp] + [-PropertyNamesToExclude ] [] +``` + +## ALIASES + +This cmdlet has the following aliases, + +## DESCRIPTION + +## EXAMPLES + +### Example 1 + +## PARAMETERS + +### -DifferenceCommandHelp + +```yaml +Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -PropertyNamesToExclude + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -ReferenceCommandHelp + +```yaml +Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: true + 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 + +### Microsoft.PowerShell.PlatyPS.Model.CommandHelp + +## OUTPUTS + +### System.String + +## NOTES + +## RELATED LINKS From b46e7cf1e8175393311a4ee24c4b5a230b7e03d1 Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Tue, 1 Jul 2025 11:06:48 -0700 Subject: [PATCH 4/4] Update measure test --- test/Pester/MeasurePlatyPSMarkdown.Tests.ps1 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/test/Pester/MeasurePlatyPSMarkdown.Tests.ps1 b/test/Pester/MeasurePlatyPSMarkdown.Tests.ps1 index 87f98e32..8f86e589 100644 --- a/test/Pester/MeasurePlatyPSMarkdown.Tests.ps1 +++ b/test/Pester/MeasurePlatyPSMarkdown.Tests.ps1 @@ -13,10 +13,10 @@ Describe "Export-MarkdownModuleFile" { It "Should identify all the '' assets" -TestCases @( @{ fileType = "unknown"; expectedCount = 2 } - @{ fileType = "CommandHelp"; expectedCount = 39 } + @{ fileType = "CommandHelp"; expectedCount = 40 } @{ fileType = "ModuleFile"; expectedCount = 14 } @{ fileType = "V1Schema"; expectedCount = 49 } - @{ fileType = "V2Schema"; expectedCount = 4 } + @{ fileType = "V2Schema"; expectedCount = 5 } ) { param ($fileType, $expectedCount) $idents.Where({($_.FileType -band $fileType) -eq $fileType}).Count | Should -Be $expectedCount