See the docstring of my function with Visual Studio Code

Question

I'm new to Visual Studio Code, I'm starting to use it to develop PowerShell scripts.

I see that when I let my cursor on the name of a function I get an overview of the parameters of the function, yet when I do it with my own custom functions, it does not do it.

How do I declare a documentation for my PowerShell functions that can be displayed in the overview by Visual Studio Code ?

I tried to do this :

<#
.Description
Get-Function displays the name and syntax of all functions in the session.
#>
function test([string]$print){}


<# Setup the working directories if they do not exist #>
If(!(Test-Path $WORKING_DIRECTORY)) {test}

But that doesn't seem to work.

Thanks a lot

score 4 · Accepted Answer · answered Nov 08 '19 at 16:57

Adding .PARAMETER to the description worked for me. Also note I believe you have to save and run the script once for it to show.

<#
.Description
Get-Function displays the name and syntax of all functions in the session.
.PARAMETER  
#>

function test([string]$print){Write-Host $print}

If(Test-Path $env:userprofile) {test -print "Test123"}

https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-6

score 1 · Answer 2 · answered Nov 08 '19 at 17:23

My previous answer was incorrect, though reading up on Comment Based Help is still a good idea for generally documenting your cmdlets.

In order for vscode to be able to know about your function definitions, the function needs to be defined in its internal Powershell host. If you can open the Powershell Integrated terminal, you can dot-source (run the script like . myScript.ps1 to read the function definitions in. You may need to make sure the script wasn't dot-sourced before running any code to execute (basically put your runtime code in an if block checking if the script was dot-sourced but leave your function definitions outside of this conditional).

Once the script has been dot-sourced in the Powershell Integrated terminal you will get the usage tooltip popup like you want. To make this "automatic", dot-source the script from $profile as resolved from the vsvode terminal.

This isn't particularly ideal and I am hoping to find a more streamlined solution, as having to dot-source every script I'm working with is cumbersome.

score 0 · Answer 3 · answered Oct 21 '22 at 14:08

You need to save and run the script, so changes in the inline documentation is recognized. I also can recommend using the .SYNOPSIS 'tag', that way it is even possible to read the text.

Example:

<#
    .SYNOPSIS
        Returns something
#>
function Get-SomeThing {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]$Path
    )

}

shows something like this when hovering the function name or for code completion:

See the docstring of my function with Visual Studio Code

3 Answers3