none
Documenting My Scripts... Any idea / Ready Documents to follow?

    Question

  • Hello,

    I want to document all my scripts for future reference and to describe what each script does, from where it pick the file paths, what result it gets and where it dumps the result.. Thinking of something similar to this to start writing my own document for each script I have done.

    Anyone can help me to a good direction?

    Thanks,

    Saturday, July 27, 2013 10:40 AM

Answers

  • If you're using PowerShell, comment-based help is nice.  Anyone who is using your script can then read it anytime by typing Get-Help <Script Path>.

    Get-Help about_Comment_Based_Help provides all the details on this.  I created a "comment-based help block" snippet in the ISE on my computers, which contains the elements I'm most likely to use (though not all at once):

    <#
    .Synopsis
       Short description
    .DESCRIPTION
       Long description
    .PARAMETER <Name>
       Descrption of parameter <Name>
    .EXAMPLE
       Example of how to use this cmdlet
    .EXAMPLE
       Another example of how to use this cmdlet
    .INPUTS
       Inputs to this cmdlet (if any)
    .OUTPUTS
       Output from this cmdlet (if any)
    .NOTES
       General notes
    .COMPONENT
       The component this cmdlet belongs to
    .ROLE
       The role this cmdlet belongs to
    .FUNCTIONALITY
       The functionality that best describes this cmdlet
    .LINK
       Name of another help topic, or a URI.  If multiple Links are needed,
       use multiple .LINK keywords (only the line immediately after .LINK is read.
    .EXTERNALHELP  <XML Help File>
       Specifies an XML-based help file for the script or function.  
    .FORWARDHELPTARGETNAME <Command-Name>
       Redirects to the help topic for the specified command. You can redirect
       users to any help topic, including help topics for a function, script,
       cmdlet, or provider. 
    .FORWARDHELPCATEGORY  <Category>
       Specifies the help category of the item in ForwardHelpTargetName.
       Valid values are Alias, Cmdlet, HelpFile, Function, Provider, General,
       FAQ, Glossary, ScriptCommand, ExternalScript, Filter, or All. Use this
       keyword to avoid conflicts when there are commands with the same name.
    #>

    Saturday, July 27, 2013 3:27 PM
  • CBH (comment based help) is strongly recommended because it enforces a consistency on the style of information presented and allows the potential user to view the help text in a few different levels of detail.

    That said, it does not take the place of regular comments. CBH typically provides information to the user of the code as to *how* to use it, while comments placed in the body typically document the intent of parts of the code (i.e. *(how* it works), and are of more use to those maintaining the code than to those using it.

    Finally, if you have a script or function that is particularly detailed, complex, or whose use is less intuitive, you might find that a full set of documentation would occupy too large a portion of the script file. In some cases you might want to keep the CBH a bit more basic, and maintain external documentation file(s). Depending on your environment, you might then include URLs to these files in the .LINK section of the CBH.


    Al Dunbar -- remember to 'mark or propose as answer' or 'vote as helpful' as appropriate.

    Saturday, July 27, 2013 11:20 PM

All replies

  • If you're using PowerShell, comment-based help is nice.  Anyone who is using your script can then read it anytime by typing Get-Help <Script Path>.

    Get-Help about_Comment_Based_Help provides all the details on this.  I created a "comment-based help block" snippet in the ISE on my computers, which contains the elements I'm most likely to use (though not all at once):

    <#
    .Synopsis
       Short description
    .DESCRIPTION
       Long description
    .PARAMETER <Name>
       Descrption of parameter <Name>
    .EXAMPLE
       Example of how to use this cmdlet
    .EXAMPLE
       Another example of how to use this cmdlet
    .INPUTS
       Inputs to this cmdlet (if any)
    .OUTPUTS
       Output from this cmdlet (if any)
    .NOTES
       General notes
    .COMPONENT
       The component this cmdlet belongs to
    .ROLE
       The role this cmdlet belongs to
    .FUNCTIONALITY
       The functionality that best describes this cmdlet
    .LINK
       Name of another help topic, or a URI.  If multiple Links are needed,
       use multiple .LINK keywords (only the line immediately after .LINK is read.
    .EXTERNALHELP  <XML Help File>
       Specifies an XML-based help file for the script or function.  
    .FORWARDHELPTARGETNAME <Command-Name>
       Redirects to the help topic for the specified command. You can redirect
       users to any help topic, including help topics for a function, script,
       cmdlet, or provider. 
    .FORWARDHELPCATEGORY  <Category>
       Specifies the help category of the item in ForwardHelpTargetName.
       Valid values are Alias, Cmdlet, HelpFile, Function, Provider, General,
       FAQ, Glossary, ScriptCommand, ExternalScript, Filter, or All. Use this
       keyword to avoid conflicts when there are commands with the same name.
    #>

    Saturday, July 27, 2013 3:27 PM
  • although the .parameter token can be included in the main help comment as David shows above, parameter specific help can be added to the parameter definitions in the PARAM block instead:

    PARAM (
    
        # name of the file
        $filename,
    
        <# this parameter is harder to explain
           so I have used a text block to provide
           its description
        #>
        $gobbledygook,
    
        # but this multi-line
        # style works as well
        $count
    
    )
    

    This style is more self-maintaining because:

    1. the name of the parameter that appears in the help is always correct, as it uses the actual name given when the parameter is defined rather than a copy of the name typed after the .PARAMETER keyword. this is useful to avoid typos and when the name of a parameter is changed.
    2. the parameter help disappears when a parameter is deleted. This helps make the help information more consistent with the actual code.


    Al Dunbar -- remember to 'mark or propose as answer' or 'vote as helpful' as appropriate.

    Saturday, July 27, 2013 10:57 PM
  • Note also that comment-based help comment blocks can be used to document scripts *and* functions. They need to appear as the first or last element of the script or function, however function help can also immediately precede the function keyword.


    Al Dunbar -- remember to 'mark or propose as answer' or 'vote as helpful' as appropriate.

    Saturday, July 27, 2013 11:06 PM
  • CBH (comment based help) is strongly recommended because it enforces a consistency on the style of information presented and allows the potential user to view the help text in a few different levels of detail.

    That said, it does not take the place of regular comments. CBH typically provides information to the user of the code as to *how* to use it, while comments placed in the body typically document the intent of parts of the code (i.e. *(how* it works), and are of more use to those maintaining the code than to those using it.

    Finally, if you have a script or function that is particularly detailed, complex, or whose use is less intuitive, you might find that a full set of documentation would occupy too large a portion of the script file. In some cases you might want to keep the CBH a bit more basic, and maintain external documentation file(s). Depending on your environment, you might then include URLs to these files in the .LINK section of the CBH.


    Al Dunbar -- remember to 'mark or propose as answer' or 'vote as helpful' as appropriate.

    Saturday, July 27, 2013 11:20 PM