Placing Comment-Based Help
What an amazing event. I’m now reading through each of the Advanced entries in a vain attempt to whittle the entries down to a short list. It’s an incredibly difficult task, which is testament to your skill and diligence. We are so lucky to have so many competent scripters in the community.
As I read through the comments on each script, I’ve noticed several that say:
“Help should be nested under the function to work properly.”
Au contraire! This is not true and I want to make sure that people who see this comment are not misled. The Windows PowerShell team designed comment-based help to be really flexible.
As I explained in about_Comment_Based_Help, you can put comment-based help for a function in one of three positions:
- At the beginning of the function body
- At the end of the function body
- On the line before the Function keyword
So, all of these work.
function Move-OldFiles { <# .Synopsis Moves old log files to an archive directory. #> Param ( [parameter(Mandatory=$true)] [String] $InputDirectory ) }function Move-OldFiles
{
Param
(
[parameter(Mandatory=$true)]
[String]
$InputDirectory
)
#Script logic goes here
<#
.Synopsis
Moves old log files to an archive directory.
#>
}<# .Synopsis Moves old log files to an archive directory. #> function Move-OldFiles { Param ( [parameter(Mandatory=$true)] [String] $InputDirectory ) #Script logic goes here } If you place the comment-based help on the line before the Function keyword, make sure that there is, at most, one blank line between the end of the comment-based help and the line with the function keyword. To avoid this problem, I always make sure that there are no blank lines between the end of the comment-based help and the Function keyword.
When reading the comments about your solutions, please remember that we are all volunteers. Everyone who takes the time to comment on your solution is trying to help, and should be appreciated, but not every comment is correct. Trust, but verify!
Related Articles
PowerShell Escape Room
PowerShell Escape Room by Michiel Hamers by Michiel Hamers https://about.me/michielhamers/ Why on earth you want to create an Escape Room with PowerShell as backend? I’ve always been a fan of escape rooms, so I decided to create my own for my kids. I wanted to make it something that would be challenging and fun for them, but also educational. I decided to use PowerShell as the backend for the escape room, as I’m a PowerShell developer and I thought it would be a great way to learn more about the language.
Microsoft Graph PowerShell Module: Getting Started Guide
Microsoft Graph PowerShell Module: Getting Started Guide by Jeff Brown Microsoft is retiring the Azure AD Graph API sometime after June 30, 2023 (announcement). This retirement includes the Azure AD PowerShell module. In its place, Microsoft has released the Microsoft Graph PowerShell module. The Microsoft Graph PowerShell module is the next-generation way of managing Microsoft cloud services using PowerShell. If you have used MSOnline or Azure AD PowerShell in the past, you’ll need to read on to learn about this new module.
ICYMI: PowerShell Week of 08-October-2021
Topics include VMWare, Windows 11, Web Reports and more… Special thanks to Robin Dadswell, Prasoon Karunan V, Kiran Patnayakuni and Kevin Laux How to gather your vCenter inventory data with this VMware PowerShell script by Scott Matteson on 7th October Inventory reports are a common request when administering a VMware vCenter environment. Learn how this VMware PowerShell script can make such requests quick and easy Building a Web Report in PowerShell, use the -Force Luke by Chris Noring on 8th October