How to create EXAMPLE function help text

This topic contains 2 replies, has 2 voices, and was last updated by Profile photo of Anthony Stringer Anthony Stringer 7 months ago.

  • Author
    Posts
  • #38925
    Profile photo of Anthony Stringer
    Anthony Stringer
    Participant

    having trouble creating EXAMPLE help text for a fucntion.

    here is the function

    #.EXAMPLE
    #    $var = 'Sid'
    #    Get-Hello $var
    #
    #    This command will return "Hello Sid!"
    #
    #.EXAMPLE
    #    Get-Hello
    #
    #    This command will return "Hello World!"
    
    function Get-Hello {
        param (
            $name = 'World'
        )
    
        return "Hello $name!"
    }
    

    here is what the first example looks like when i run Get-Help Get-Hello -Examples. note, the second line is not prefixed by 'PS C:\>' and there are 3 empty lines before the second example

    	-------------------------- EXAMPLE 1 --------------------------
        
        PS C:\>$var = 'Sid'
        
        
        Get-Hello $var
        
        This command will return "Hello Sid!"
        
        
        
        
        -------------------------- EXAMPLE 2 --------------------------
    

    desired result is like example 6 of Get-Help Get-ChildItem -Examples. both commands are prefixed by 'PS C:\>' and there are only two blank lines before the next example

    	-------------------------- EXAMPLE 6 --------------------------
    
        PS C:\>Import-Module Microsoft.PowerShell.Security
        PS C:\>Get-ChildItem -Path Cert:\* -Recurse -CodeSigningCert
    
    
        This command gets all of the certificates in the Windows PowerShell Cert: drive that have code-signing authority.
    
        The first command imports the Microsoft.PowerShell.Security module into the session. This module includes the
        Certificate provider that creates the Cert: drive.
    
        The second command uses the Get-ChildItem cmdlet. The value of the Path parameter is the Cert: drive. The Recurse
        parameter requests a recursive search. The CodeSigningCertificate parameter is a dynamic parameter that the
        Certificate provider adds to the Get-ChildItem cmdlet. This parameter gets only certificates that have code-signing
        authority.
    
        For more information about the Certificate provider and the Cert: drive, go to
        http://go.microsoft.com/fwlink/?LinkID=113433 or use the Update-Help cmdlet to download the help files for the
        Microsoft.PowerShell.Security module and then type "Get-Help Certificate".
    
    
        -------------------------- EXAMPLE 7 --------------------------
    
  • #38946
    Profile photo of Christian Sandfeld
    Christian Sandfeld
    Participant

    Hi Anthony,

    Check out this blog article by June Blender, where she explains some of the intricacies of comment based help:

  • #38948
    Profile photo of Anthony Stringer
    Anthony Stringer
    Participant

    thanks for the read, however, i was unable to find information regarding multiline examples, and noticed something not quite right with microsoft's own documentation

    this link
    https://technet.microsoft.com/library/hh847834.aspx
    says if you have this

    .EXAMPLE
    C:\PS> extension -name "File"
    File.txt
    

    your result will look like this

    -------------------------- EXAMPLE 1 --------------------------
    
    C:\PS> extension -name "File"
    File.txt
        
    -------------------------- EXAMPLE 2 --------------------------
    

    which i was unable to reproduce in my own testing

You must be logged in to reply to this topic.