PoshCode | PoshCode Modules for Packaging Searching | Command Line Interface library

It's called "comment-based help" (about_Comment_Based_Help)

You have 3 options where to put the documentation:

• At the beginning of the function body.

• At the end of the function body.

• Before the function keyword. There cannot be more than one blank line between the last line of the function help and the function keyword.

So, you can easily put them at the top of your function (either inside or outside):

You can avoid the problem by not using a module qualifier not using a noun prefix when you call your module's own functions.

That is, call them as Verb-Noun, exactly as named in the target function's implementation.

• This is generally safe, because your own module's functions take precedence over any commands of the same name defined outside your module.

  • The sole exception is if an alias defined in the global scope happens to have the same name as one of your functions - but that shouldn't normally be a concern, because aliases are used for short names that do not follow the verb-noun naming convention.

• It also makes sense in that it allows you to call your functions module-internally with an invariable name - a name that doesn't situationally change, depending on what the caller decided to choose as a noun prefix via Import-Module -Prefix ....

  • Think of the prefix feature as being a caller-only feature that is unrelated to your module's implementation.

As an aside: As of PowerShell 7.0, declaring a default noun prefix via the DefaultCommandPrefix module-manifest property doesn't properly integrate with the module auto-loading and command-discovery features - see this GitHub issue.