Get-AutoHelp.ps1

1. <# 
2. .SYNOPSIS 
3.     A summary of what this script does 
4.     In this case, this script documents the auto-help text
5.     in PowerShell CTP 3 
6.     Appears in all basic, -detailed, -full, -examples 
7. .DESCRIPTION 
8.     A more in depth description of the script 
9.     Should give script developer more things to talk about 
10.     Hopefully this can help the community too 
11.     Becomes: "DETAILED DESCRIPTION" 
12.     Appears in basic, -full and -detailed 
13. .NOTES 
14.     Additional Notes, eg 
15.     File Name  : get-autohelp.ps1 
16.     Author     : Thomas Lee - tfl@psp.co.uk 
17.     Requires   : PowerShell V2 CTP3 
18.     Appears in -full  
19. .LINK 
20.     A hyper link, eg 
21.     http://www.pshscripts.blogspot.com/2008/12/get-autohelpps1.html 
22.     Becomes: "RELATED LINKS"  
23.     Appears in basic and -Full 
24. .EXAMPLE 
25.     The first example - just text documentation 
26.     You should provide a way of calling the script, plus
27.     any expected output, eg:
28.          C:\foo> .\get-autohelp.ps1 42
29.          The meaning of life is 42
30.     Appears in -detailed and -full 
31. .EXAMPLE 
32.     The second example - more text documentation 
33.     This would be an example calling the script differently. You
34.     have lots and lots, and lots of examples if this is useful. 
35.     Appears in -detailed and -full 
36. .INPUTTYPE 
37.    Documentary text, eg: 
38.    Input type  [Universal.SolarSystem.Planetary.CommonSense] 
39.    Appears in -full 
40. .RETURNVALUE 
41.    Documentary Text, e,g: 
42.    Output type  [Universal.SolarSystem.Planetary.Wisdom] 
43.    Appears in -full 
44. .COMPONENT 
45.    Not sure how to specify or use 
46.    Does not appear in basic, -full, or -detailed 
47.    Should appear in -component 
48. .ROLE  
49.    Not sure How to specify or use 
50.    Does not appear in basic, -full, or -detailed 
51.    Should appear with -role 
52. .FUNCTIONALITY 
53.    Not sure How to specify or use 
54.    Does not appear in basic, -full, or -detailed 
55.    Should appear with -functionality 
56. .PARAMETER foo 
57.    The .Parameter area in the script is used to derive the
58.    of the PARAMETERS in Get-Help output which documents the
59.    parameters in the param block. The section takes a
60.    value (in this case foo,  the name of the first actual
61.    parameter), and only appears if there is parameter of
62.    that name in the param block. Having a section for a
63.    parameter that does not exist generate no extra output
64.    of this section   
65.    Appears in -detailed, -full (with more info than in -det)
66.    Appears in -Parameter (need to specify the parameter name) 
67. .PARAMETER bar 
68.    Example of a parameter definition for a parameter that does not exist. 
69.    Does not appear at all. 
70. #> 
71.  
72. # Note above section does not contain entries for NAME, SYNTAX
73. # and REMARKS sections of in get-help output 
74. # 
75. # These sections appear as follows: 
76. # NAME    - generated from the name passed to get-help.  
77. # SYNTAX  - generated from param block details. 
78. # REMARKS - generated based on script name (e.g. what's shown in NAME)
79. #           inserted into some static text. 
80. # 
81. # Not sure how to generate/document -component, -role, -functionality 
82. # Not sure how to generate/use  -category 
83.  
84. param ( 
85. [Parameter(Position=0, Mandatory=$true, ValueFromPipeline=$true)]  
86. [int64] $foo=42 
87. ) 
88.  
89.  "The meaning of life is $foo!" 

Technorati Tags: PowerShell,PowerShell V2,advanced function,auto-help