CODEWITHSUNDEEP
powershellvisual-studio-code
Maxime
Maxime

Reputation: 858

See the docstring of my function with Visual Studio Code

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

Function declaration

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

Upvotes: 4

Views: 1763

Answers (4)

carlin.scott
carlin.scott

Reputation: 7265

The function needs to be declared in the Powershell Extension host for IntelliSense to display the help text. That will happen automatically when you run the PowerShell script. But you can also highlight your whole function and press F8 to 'run' it in the shell host. That command is also available from the context menu (right-click), and command pallet (ctrl+p).

The Microsoft Learn documentation for function help comments shows that we can put the documentation block immediately before the function, after the opening {, or before the closing }.

I also found a bug with detection of the block when it is above the function declaration; It only supports CRLF line-endings. So make sure you're using CRLF line-endings. Or put doc comment inside the function.

Upvotes: 1

Alex
Alex

Reputation: 5439

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:

when hovering the function name

code completion

Upvotes: 1

codewario
codewario

Reputation: 21418

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.

Upvotes: 2

Nick
Nick

Reputation: 1208

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"}

enter image description here

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

Upvotes: 4

Related Questions