Sunday 28 December 2008

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.  "The meaning of life is $foo!" 

No comments: