none
What's the standard header in PowerShell scripts (documentation)?

    Question

  • Can anyone tell me what the "standard header" that I see in a lot of PowerShell scripts is all about? I have been unable to find any explanation so far.

    Here's a snippet:

    <#  
    .SYNOPSIS  
        Counts the Grateful Dead shows in my archives  
    .DESCRIPTION  
        This script looks at my GD archive, and uses folder names to  
        determine show type (aud, sbd, etc), and checks to see what  
        shows have checked MD5s  
    .NOTES  
        File Name  : count-gdshows.ps1  
        Author     : Thomas Lee - tfl@psp.co.uk  
        Requires   : PowerShell V2 CTP3  
    .LINK  
    

    Thursday, July 16, 2009 2:00 PM

Answers

All replies

  • PowerShell v2 added this functionality, some calles it auto help or inline help. This feature lets you document your function so when a user type:

    help yourFunctionName

    He will get a help page which derives from the snippet you mention.


    You can find more information on Thomas's blog:

    Shay Levy [MVP]
    http://blogs.microsoft.co.il/blogs/ScriptFanatic
    PowerShell Toolbar
    • Marked as answer by Todd Beaulieu Thursday, July 16, 2009 4:25 PM
    Thursday, July 16, 2009 3:55 PM
  • Why I couldn't find that on my own is a mystery. Thanks!

    You mentioned documenting a "function", but this appears to document a "script". This brings up a question I've been struggling with.

    I'm new to PS and really enjoying it so far. In fact, I'm trying to use it in liew of c# for an application I was just tasked with.

    Ok, so I guess I have TWO more questions!

    1. I'm stuck in v1 right now. We chose v1 simply out of ignorance to the stability of v2. Do you think v2 is ready for prime time, to be used for internal production code?

    2. Function vs. Script: What are your thoughts on organizing your code? Do you mash reusable functions into larger scripts? Do you split them all out into individual scripts? What about an "application" ... do you just define a bunch of functions and then at the very end (or begining?) start calling them?

    In my proof of concept I just threw everything in, inline. Now I'm trying to refactor it out and I'm not sure the best way to do it.

    Thank you!

    Thursday, July 16, 2009 4:25 PM
  • The help data can be used inside a function body or in a script. A script is not much different than a function, actually you can think of it as a function *without* a name, the name is the script name. You can a function like:


    function foo
    {

    <# 
    .SYNOPSIS 
        Counts the Grateful Dead shows in my archives

    (...)
    #>


       param($a,$b)

       $a+$b
    }

    And execute it like:

    foo -a 3  -b 4


    or write the function body in a script file called foo.ps1 :

    ## foo.ps1 ##

    <# 
    .SYNOPSIS 
        Counts the Grateful Dead shows in my archives

    (...)
    #>

       param($a,$b)

       $a+$b

    #########


    and execute it like so:


    .\foo.ps1 -a 3 -b 4


    they give the same output. Windows 7 is goiung to RTM soon and as you probably know PowerShell v2 ships with it, so you can switch to v2 in the very near future. I'm working with v2 since the CTP versions (on my production machine) and it is working very good, lots of new exiting stuff!


    As for functions vs scripts... it depends. On my personal machine I save my functions in various ways. I categorize them and save each bunch in a seperate script file (i.e. utilities.ps1, exchange.ps1, ad.ps1 etc). Some files I use more on a regular basis so I dot-source them in my profile, other scripts I load when I need. v2 introduced a module concept so the next evolution of my script files will turn into modules.  I also implement some functions in ps1xml files, these are used to extend objects , via PowerShells' Extended Type System (ETS), you can find an example on my blog (http://blogs.microsoft.co.il/blogs/scriptfanatic/archive/2009/05/31/getting-certificates-expiration.aspx).


    Shay Levy [MVP]
    http://blogs.microsoft.co.il/blogs/ScriptFanatic
    PowerShell Toolbar
    Thursday, July 16, 2009 7:47 PM
  • PowerShell v2 added this functionality, some calles it auto help or inline help. This feature lets you document your function so when a user type:

    help yourFunctionName

    He will get a help page which derives from the snippet you mention.


    You can find more information on Thomas's blog:
    Thanks Shay for the references.

    The header that Todd asked about came from one of my scripts (posted to http://pshscripts.blogspot.com - from which you can download the full libarary of PowerShell scripts). I've taken to documenting all my scripts using this format. I call this autohelp as with V2, you can use these comments to integrate with Get-Help. I'm particularly fond of V2's Module feature, which is also documented using the same convention.

    And I hope Todd has a great GD Collection to use my scripts against. If not - he sould contact me...


    Thomas Lee
    Tuesday, August 04, 2009 5:51 PM