PowerShell/platyPS

Support for Default Command Prefix

EmeraldFlame opened this issue · 0 comments

Summary of the new feature / enhancement

Currently, when using New-MarkdownHelp all references to functions are generated with their as-written names. However, if you are using the "DefaultCommandPrefix" value in your module manifest those references no longer line up with what your end-user would actually see on their end.

This issue is compounded because even if I manually change those references to use the Default Command Prefix manually, when running Update-MarkdownHelp, many of those corrected references get reverted.

For example, one command I frequently use in multiple modules Connect-Api. This then gets augmented by the command prefix, so a module for "Random Service" may show up to the end user as Connect-RSApi.

While this could cause some confusion if someone manually over-rides the default command prefix, as the Get-Help documentation would no longer match in that case, given the options this seems preferable. If someone is manually over-riding the default prefix, that person will already be aware they made a change to command names, so they can match up the documentation on their own.

Where-as when an end-user who is just using the default prefix, they may not be aware that prefix is in use at all. This could cause confusion, as they would see Get-Help documentation referencing and showing examples of the non-prefixed commands, likely leading them to attempt to run them without the prefix. It seems like it'd have a significant benefit for end-users to include the prefix in the Get-Help documentation.

Proposed technical implementation details (optional)

Add a "DefaultCommandPrefix" parameter to New-MarkdownHelp and Update-MarkdownHelp that would augment the references to the commands in the associated markdown help files so that they match what end users would expect by default when a "DefaultCommandPrefix" is included in the module manifest.