How to add value to description property of a powershell function? - powershell

Question

I would like to populate the Description property of Powershell functions I create in my $PROFILE. I would like to add a value to the Description property such as "Created in personal PROFILE". Is this possible?
Currently if I examine the Description of my Functions I find none are populated, for example:
Get-Command -Type Function -Name get-* | Select-Object -Property Name, Description -First 10
Name Description
---- -----------
Get-AlertLog
Get-AllColors
Get-AppBackgroundTask
Get-AppvVirtualProcess
Get-AppxLastError
Get-AppxLog
Get-AssignedAccess
Get-AutologgerConfig
Get-BCClientConfiguration
Get-BCContentServerConfiguration
Having the value populated would allow me to search for and quickly see where my functions were created, or what they do, etc.
Thank You.
+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~
Note:
I do not want to retrieve the information via Get-Help, but rather populate some of the properties of Type: System.Management.Automation.FunctionInfo:
Get-Command -Type Function -Name Get-AllColors | Get-Member
TypeName: System.Management.Automation.FunctionInfo
Name MemberType Definition
---- ---------- ----------
Equals Method bool Equals(System.Object obj)
GetHashCode Method int GetHashCode()
GetType Method type GetType()
ResolveParameter Method System.Management.Automation.ParameterMetadata ResolveParameter(string name)
ToString Method string ToString()
CmdletBinding Property bool CmdletBinding {get;}
CommandType Property System.Management.Automation.CommandTypes CommandType {get;}
DefaultParameterSet Property string DefaultParameterSet {get;}
Definition Property string Definition {get;}
Description Property string Description {get;set;}
HelpFile Property string HelpFile {get;}
Module Property psmoduleinfo Module {get;}
ModuleName Property string ModuleName {get;}
Name Property string Name {get;}
Noun Property string Noun {get;}
Options Property System.Management.Automation.ScopedItemOptions Options {get;set;}
OutputType Property System.Collections.ObjectModel.ReadOnlyCollection[System.Management.Automation.PS...
Parameters Property System.Collections.Generic.Dictionary[string,System.Management.Automation.Paramet...
ParameterSets Property System.Collections.ObjectModel.ReadOnlyCollection[System.Management.Automation.Co...
RemotingCapability Property System.Management.Automation.RemotingCapability RemotingCapability {get;}
ScriptBlock Property scriptblock ScriptBlock {get;}
Source Property string Source {get;}
Verb Property string Verb {get;}
Version Property version Version {get;}
Visibility Property System.Management.Automation.SessionStateEntryVisibility Visibility {get;set;}
HelpUri ScriptProperty System.Object HelpUri {get=$oldProgressPreference = $ProgressPreference...
Another way to ask is "Why is there such a Type if there is not way to populate the Properties with values and retrieve them via Select-Object -Property?"
Thank You.

Answer 1

You should use comment based help instead of usage functions. Comment based help will allow you to work with the build in help system of PowerShell. It isn't hard to write and you don't even need to use all the sections.
Here is the TechNet on about_Comment_Based_Help, with some examples:
The syntax for comment-based Help is as follows:
# .< help keyword>
# <help content>
-or -
<#
.< help keyword>
< help content>
#>
You do have to make sure the categories are spelled correctly, otherwise the whole help on your function won't show up and you won't get an error message. A simple example that just has a synopsis and a description:
.SYNOPSIS
A brief description of the function or script. This keyword can be used
only once in each topic.
.DESCRIPTION
A detailed description of the function or script. This keyword can be
used only once in each topic.
Read the linked article for all the keywords and their descriptions. Similar information can be found by running get-help about_comment_based_help

Answer 2

So far the responses do not answer the actual question as asked, and it is a good question as is, even though adding Help is a good and useful idea, whether it is Comment Based or full XML Help.
The problem is that Comment Based Help only provides the "Description" for the functions HELP, and not it's properties as shown when you run Get-Command.
Getting the Description with Get-Command is a very useful and separate idea.
However, only some properties of a function are (directly) settable and we can discover this with Get-Member -membertype Property as shown in the original question and whose output includes (part of) the answer:
Description Property string Description {get;set;}
Member property 'Description' is directly SETTABLE, as shown as the end of the definition for the property: {get;set;}:
ANSWER: So we can easily set the functions actual Definition property with a direct assignment:*
(Get-Command -Type Function -Name Get-AllColors).Description = 'Defined in $Profile'
# or
(Get-Command -Type Function -Name Get-AllColors).Description = "Defined in the $Profile"
We can find all properties which are directly settable quite easily.
gcm mypshost | get-member | findstr "set;"
# Typically only shows 3 properties unless the function was defined in a module
Description
Options
Visibility
Or perhaps even better would be setting the "Source" property which is now included in the default output from Get-Command (though that is not so trivially set with direct assignment.)
Creating the function within a Module with a proper "Module Manifest" does allow for setting most/all of these properties that are typically blank on functions defined directly.
The Source will be the "module" that defines the function and the version will be set as well if it is set in the module.
Unfortunately, the "Set-ItemProperty" command is not supported by the "Function" PSProvider (as it is by the Registry Provider and many others. The following fails (on Version 2.0 and 5.1):
Set-ItemProperty function:mypshost -Name Description -Value 'only testing'
While it works with similar syntax for a file:
Set-ItemProperty (dir ic.ps1) -Name LastWriteTime -Value (get-date)
Another example is the "OutputType" which can be set by using one of the options in the [CmdletBinding()] attribute of an advanced function parameter block:

Answer 3

You can use Comment-Based Help to add a description (and lots of other information) to your functions:
SYNTAX FOR COMMENT-BASED HELP
The syntax for comment-based help is as follows:
# .< help keyword>
# <help content>
-or -
<#
.< help keyword>
< help content>
#>
Example:
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
.DESCRIPTION
Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.
}

Answer 4

I think what HerbM is looking for is a quick reminder what a function does, not a replacement for help. There is a good case for both. For example,I have a function that displays a list of commands and then executes them. If I enter:
EXAMPLE
gcm na|select -property name,description,DisplayName
Name Description DisplayName
---- ----------- -----------
NA RB Do a command with no arguments. NA -> Do_Noarg
GCM lists a short description that I included when I created the alias NA.
It would be useful if GCM would also list the description on functions instead of blanks as follows:
EXAMPLE
gcm do_noarg|select -property name,description,Definition
Name Description Definition
---- ----------- ----------
Do_Noarg dr ~\PS1\No_Arg\*.ps1 Invoke-Expression
I believe HerbM isn’t looking for gcm or any other tool to replace help but Just wants a quick single line description of a function.
If Description is just a placeholder for future releases of “function”, then please let everyone know.