PowerShell · sdwheeler · Oct 22, 2024 · Oct 22, 2024
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,9 +1,12 @@
-CHANGELOG
--------------
+# CHANGELOG
 
 ## Not released
 
-# 0.14.2
+## 1.0.0-preview1
+
+- Total rewrite of the module in C#
+
+## 0.14.2
 
 - Add HelpInfoUri for platyPS module
 - CI changes to exclude build on v2 branch
@@ -13,21 +16,21 @@ CHANGELOG
   - Make sure for script module .psm1 is added to the external help file metadata for nested module
 - New-Yaml help generates YAML for common parameters
 
-# 0.14.1
+## 0.14.1
 
 - Fix appveyor build script
   - Update-Help for selected modules only
   - Pin Pester to version 4.10.1
 - Add makecab directive to set size limit to `CDROM`
 
-# 0.14.0
+## 0.14.0
 
 * Fix passing `ExcludeDontShow` flag to modules (#459)
 * Make `CommonParameters` text use proper link format (#449)
 * Modified `GetSchemaVersion` function to assume `2.0.0` if no schema version found (#452)
 * Fix errors for `New-MarkdownHelp` `ps1` input (#450)
 
-# 0.13.0
+## 0.13.0
 
 * Fix `Update-MarkdownHelp` to not rewrite files if there are not updates (#412) (Thanks @iricigor)
 * Add `-ModulePagePath` parameter to `New-MarkdownHelp` for better placement of generated file (#416) (Thanks @PrzemyslawKlys)

diff --git a/README.md b/README.md
@@ -1,123 +1,131 @@
-[![Build status](https://ci.appveyor.com/api/projects/status/u65tnar0cfkmqywl/branch/master?svg=true)](https://ci.appveyor.com/project/PowerShell/markdown-maml/branch/master)
-[![Build status](https://travis-ci.org/PowerShell/platyPS.svg?branch=master)](https://travis-ci.org/PowerShell/platyPS/builds)
-
-[![Join the chat at https://gitter.im/PowerShell/platyPS](https://badges.gitter.im/PowerShell/platyPS.svg)](https://gitter.im/PowerShell/platyPS?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-
 # PlatyPS
 
 PlatyPS provides a way to:
 
-* Write PowerShell External Help in Markdown
-* Generate markdown help ([example](docs/Update-MarkdownHelp.md)) for your existing modules
-* Keep markdown help up-to-date with your code
+- Write PowerShell External Help in Markdown
+- Generate markdown help
+- Keep markdown help up-to-date with your code
+- Create updateable help files
 
-Markdown help docs can be generated from old external help files (also known as MAML-xml help), the command objects (reflection), or both.
-
-PlatyPS can also generate cab files for [`Update-Help`](https://technet.microsoft.com/en-us/library/hh849720.aspx).
+Markdown help docs can be generated from old external help files (also known as MAML-xml help), the
+command objects (reflection), or both.
 
 ## Why?
 
-Traditionally PowerShell external help files have been authored by hand or using complex tool chains and rendered as MAML XML for use as console help.
-MAML is cumbersome to edit by hand, and common tools and editors don't support it for complex scenarios like they do with Markdown. PlatyPS is provided as a solution for allow documenting PowerShell help in any editor or tool that supports Markdown.
+Traditionally PowerShell external help files have been authored by hand or using complex tool chains
+and rendered as MAML XML for use as console help. MAML is cumbersome to edit by hand, and common
+tools and editors don't support it for complex scenarios like they do with Markdown. PlatyPS is
+provided as a solution for allow documenting PowerShell help in any editor or tool that supports
+Markdown.
 
-An additional challenge PlatyPS tackles, is to handle PowerShell documentation for complex scenarios (e.g. very large, closed source, and/or C#/binary modules) where it may be desirable to have documentation abstracted away from the codebase. PlatyPS does not need source access to generate documentation.
+An additional challenge PlatyPS tackles, is to handle PowerShell documentation for complex scenarios
+(e.g. very large, closed source, and/or C#/binary modules) where it may be desirable to have
+documentation abstracted away from the codebase. PlatyPS doesn't need source access to generate
+documentation.
 
-Markdown is designed to be human-readable, without rendering. This makes writing and editing easy and efficient. 
-Many editors support it ([Visual Studio Code](https://code.visualstudio.com/), [Sublime Text](http://www.sublimetext.com/), etc), and many tools and collaboration platforms (GitHub, Visual Studio Online) render the Markdown nicely.
+Markdown is designed to be human-readable, without rendering. This makes writing and editing easy
+and efficient. Many editors support it, including [Visual Studio Code][04], and many tools and
+collaboration platforms (GitHub, Visual Studio Online) render the Markdown nicely.
 
 ## Common setups
 
 There are 2 common setups that are used:
 
 1. Use markdown as the source of truth and remove other types of help.
-2. Keep comment based help as the source of truth and periodically generate markdown for web-site publishing.
+1. Keep comment based help as the source of truth and periodically generate markdown for web-site
+   publishing.
 
-They both have advantages and use-cases, you should decide what's right for you.
-There is slight preference toward number 1 (markdown as the source).
+They both have advantages and use-cases, you should decide what's right for you. There is slight
+preference toward number 1 (markdown as the source).
 
 ## Quick start
 
-* Install platyPS module from the [PowerShell Gallery](https://www.powershellgallery.com/packages/platyPS):
+- Install platyPS module from the [PowerShell Gallery][07]:
 
 ```powershell
 Install-Module -Name platyPS -Scope CurrentUser
 Import-Module platyPS
 ```
 
-* Create initial Markdown help for `MyAwesomeModule` module:
+- Create initial Markdown help for `MyAwesomeModule` module:
 
 ```powershell
 # you should have module imported in the session
 Import-Module MyAwesomeModule
 New-MarkdownHelp -Module MyAwesomeModule -OutputFolder .\docs
 ```
 
-* Edit markdown files in `.\docs` folder and populate `{{ ... }}` placeholders with missed help content.
+- Edit markdown files in `.\docs` folder and populate `{{ ... }}` placeholders with missed help content.
+- Create external help from markdown help
 
-* Create external help from markdown help
+  ```powershell
+  New-ExternalHelp .\docs -OutputPath en-US\
+  ```
 
-```powershell
-New-ExternalHelp .\docs -OutputPath en-US\
-```
-
-* **Congratulations**, your help is now in markdown!
+  **Congratulations**, your help is now in markdown!
 
-* Now, if your module code changes, you can easily update your markdown help with
+- Now, if your module code changes, you can easily update your markdown help with
 
-```powershell
-# re-import your module with latest changes
-Import-Module MyAwesomeModule -Force
-Update-MarkdownHelp .\docs
-```
+  ```powershell
+  # re-import your module with latest changes
+  Import-Module MyAwesomeModule -Force
+  Update-MarkdownHelp .\docs
+  ```
 
 ### PlatyPS markdown schema
 
-Unfortunately, you cannot just write any Markdown, as platyPS expects Markdown to be authored in a **particular way**.
-We have defined a [**schema**](platyPS.schema.md) to determine how parameters are described, where scripts examples are shown, and so on.
+Unfortunately, you cannot just write any Markdown, as platyPS expects Markdown to be authored in a
+**particular way**. We have defined a [**schema**][03] to determine how parameters are described,
+where scripts examples are shown, and so on.
 
-The schema closely resembles the existing output format of the `Get-Help` cmdlet in PowerShell. 
+The schema closely resembles the existing output format of the `Get-Help` cmdlet in PowerShell.
 
-If you break the schema in your markdown, you will get error messages from `New-ExternalHelp` and `Update-MarkdownHelp`.
-You would not be able to generate extrenal help or update your markdown.
+If you break the schema in your markdown, you will get error messages from `New-ExternalHelp` and
+`Update-MarkdownHelp`. You would not be able to generate extrenal help or update your markdown.
 
 It may be fine for some scenarios, i.e. you want to have online-only version of markdown.
 
-## [Usage](docs)
+## [Usage][06]
 
 Supported scenarios:
 
-*  Create Markdown
-    *  Using existing external help files (MAML schema, XML).
-    *  Using reflection
-    *  Using reflection and existing internal external help files.
-    *  For a single cmdlet
-    *  For an entire module
-
-*  Update existing Markdown through reflection.
-
-*  Create a module page <ModuleName>.md with summary. It will also allow you to create updatable help cab.
-
-*  Retrieve markdown metadata from markdown file.
-
-*  Create external help xml files (MAML) from platyPS Markdown.
-
-*  Create external help file cab
-
-*  Preview help from generated maml file.
+- Create Markdown
+  - Using existing external help files (MAML schema, XML).
+  - Using reflection
+  - Using reflection and existing internal external help files.
+  - For a single cmdlet
+  - For an entire module
+- Update existing Markdown through reflection.
+- Create a module page `<ModuleName>.md` with summary. It will also allow you to create updatable
+  help cab.
+- Retrieve markdown metadata from markdown file.
+- Create external help xml files (MAML) from platyPS Markdown.
+- Create external help file cab
+- Preview help from generated maml file.
 
 ## Remoting
 
-PlatyPS supports working with [`Import-PSSession`](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/import-pssession?view=powershell-6) aka implicit remoting.
-Just pass `-Session $Session` parameter to the platyPS cmdlets and it will do the rest.
+PlatyPS supports working with [Import-PSSession][05] aka implicit remoting. Just pass
+`-Session $Session` parameter to the platyPS cmdlets and it will do the rest.
 
 ## Build
 
-For information about building from sources and contributing see [contributing guidelines](CONTRIBUTING.md).
+For information about building from sources and contributing see [contributing guidelines][02].
 
 ## Code of Conduct
 
-Please see our [Code of Conduct](CODE_OF_CONDUCT.md) before participating in this project.
+Please see our [Code of Conduct][01] before participating in this project.
 
 ## Security Policy
 
-For any security issues, please see our [Security Policy](SECURITY.md).
+For any security issues, please see our [Security Policy][08].
+
+<!-- link references -->
+[01]: CODE_OF_CONDUCT.md
+[02]: docs/developer/platyPS/CONTRIBUTING.md
+[03]: docs/deveopler/platyPS.schema.md
+[04]: https://code.visualstudio.com/
+[05]: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/import-pssession
+[06]: https://learn.microsoft.com/powershell/module/platyps/
+[07]: https://www.powershellgallery.com/packages/platyPS
+[08]: SECURITY.md
diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Compare-CommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Compare-CommandHelp.md
@@ -0,0 +1,134 @@
+---
+document type: cmdlet
+external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml
+HelpUri: ''
+Locale: en-US
+Module Name: Microsoft.PowerShell.PlatyPS
+ms.custom: OPS10
+ms.date: 09/17/2024
+PlatyPS schema version: 2024-05-01
+title: Compare-CommandHelp
+---
+
+# Compare-CommandHelp
+
+## SYNOPSIS
+
+Compares two **CommandHelp** objects and produces a detailed report showing the differences.
+
+## SYNTAX
+
+### __AllParameterSets
+
+```
+Compare-CommandHelp [-ReferenceCommandHelp] <CommandHelp> [-DifferenceCommandHelp] <CommandHelp>
+ [-PropertyNamesToExclude <string[]>] [<CommonParameters>]
+```
+
+## ALIASES
+
+## DESCRIPTION
+
+`Compare-CommandHelp` is a troubleshooting tool that compares two CommandHelp objects and produces a
+detailed report showing the differences. For example, you can use this to compare objects imported
+from different sources, such as two different versions of Markdown files.
+
+## EXAMPLES
+
+### Example 1
+
+```powershell
+$refcmd = Import-MarkdownCommandHelp -Path .\v1\Microsoft.PowerShell.PlatyPS\Compare-CommandHelp.md
+$diffcmd = Import-MarkdownCommandHelp -Path .\v2\Microsoft.PowerShell.PlatyPS\Compare-CommandHelp.md
+Compare-CommandHelp -ReferenceCommandHelp $refcmd -DifferenceCommandHelp $diffcmd > .\diff.log
+```
+
+## PARAMETERS
+
+### -DifferenceCommandHelp
+
+The CommandHelp object to compare against the reference object.
+
+```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
+
+A list of one or more property names to exclude from the comparison.
+
+```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
+
+The base CommandHelp object to be compared to the difference object.
+
+```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
+
+- [Import-MarkdownHelp](Import-MarkdownHelp.md)
+- [Import-YamlCommandHelp](Import-YamlCommandHelp.md)