Comment based help for multiple function in a script

This topic contains 0 replies, has 1 voice, and was last updated by  Forums Archives 5 years, 7 months ago.

  • Author
    Posts
  • #5699

    by brittfam at 2013-03-20 13:33:40

    I have written a script that has multiple functions. I successfully created comment based help for the first function. I tried to create command based help for the second function but I cannot display the help text. I created this script to distribute to others as a tool to obtain information from a database in one function. The second function takes that data and updates a table in another oracle database for metric gathering. I would like to be able to provide help for both functions. Is this possible? I have even gone as far as copying and pasting the same text that works in the first function into the second to see if it was a formatting error and I still cannot list the help for the second function. What am I missing?

    Thanks for the help in advance.

    Brian

    by DexterPOSH at 2013-03-20 16:25:24

    Hi Brian,

    Where are you placing the comment based help for your functions ?
    I usually put it just after the Function declaration....you can place help for multiple functions this way.
    function Test-Function {
    < #
    .SYNOPSIS
    A brief description of the function.

    .DESCRIPTION
    A detailed description of the function.
    ----snipped----

    Once the Function is loaded in the current PowerShell instance. Ican use 'help Test-Function" to see the help.

    P.S. Read about_comment_based_help topic if you haven't already.

    by MasterOfTheHat at 2013-03-20 19:31:35

    In order to see the comment based help for each function, though, you have to load the function into the session. that means that you have to dot-source the .ps1 or create a module of your functions and then import the module.

    by brittfam at 2013-03-21 06:55:03

    When I use get-help get-somthing in the script, I can see the help text as I expect it to be. When I use get-help insert-somthing, which is the second function in the script, I get somthing I did not expect. I am including the display of running both for clarity.

    PS C:\Users\brittw> get-help get-metrics

    NAME
    get-metrics

    SYNOPSIS
    This function is used to connect to the Oracle Database and query Authentication metrics, i.e.
    Total, Authentications over 24 hour period, Total Failed Authentication over a 24 hour period.

    SYNTAX
    get-metrics [[-Computername] ] []

    DESCRIPTION
    This script loads the .net provider for ORACLE Client which must be installed and configured prior
    to running this script. If the provider is not installed the script will error. It will run locally
    but can be used from a remote system if the proper port access is allowed to the server. The port
    can be found in the TNSNAMES file on each server. The Connection string located in the variable
    $strconnect will need to be updated for a remote connection. See connectionstrings.com for
    assistance.

    RELATED LINKS

    REMARKS
    To see the examples, type: "get-help get-metrics -examples".
    For more information, type: "get-help get-metrics -detailed".
    For technical information, type: "get-help get-metrics -full".

    PS C:\Users\brittw> get-help insert-rsametrics

    NAME
    insert-metrics

    SYNTAX
    insert-metrics [[-oracomputername] ]

    ALIASES
    None

    REMARKS
    None

    Below is a rough model of Script.ps1

    function get-somthing {
    < #
    .SYNOPSIS
    .DESCRIPTION
    .PARAMETER
    .EXAMPLE
    #>
    Param(
    $somthing = 'localhost'
    )
    BEGIN{

    }
    PROCESS{

    }
    END{

    }

    get-somthing

    Function insert-somthing {
    < #
    .SYNOPSIS
    .DESCRIPTION
    .PARAMETER
    .EXAMPLE
    #>
    param (
    $computername = 'localhost'
    )
    BEGIN{

    }
    PROCESS{

    }
    END{

    }
    }

    insert-somthing

    by DexterPOSH at 2013-03-22 16:10:48

    Hi there,

    I tried reproducing your problem, but couldn't.
    Everything seems to be working as expected.

    Only thing I could see out of ordinary for your post above is that it has ALIASES keyword there. Was it really there or you posted it wrong , as the help doesn't show any info on ALIASES in my system[quote="brittfam"]PS C:\Users\brittw> get-help insert-rsametrics

    NAME
    insert-metrics

    SYNTAX
    insert-metrics [[-oracomputername] ]

    ALIASES
    None

    REMARKS
    None[/quote]
    Also the name is different (see above in bold) but that is a typo, I guess.
    Maybe someone else would be able to point out what is the problem here.
    I am just curious as to what is causing this.

    by brittfam at 2013-03-23 18:33:13

    I just typed it wrong above. I am not sure where the ALIASES is coming fro since I did not include that in any help text. I erased the help test and started over and got the same results. I can submit a sterilized version of the entire script if someone is willing to read and help. Dont want to post a long response otherwise. I have finished the script and it works as I intended but the help is lacking.

    by brittfam at 2013-03-23 18:33:13

    I just typed it wrong above. I am not sure where the ALIASES is coming fro since I did not include that in any help text. I erased the help test and started over and got the same results. I can submit a sterilized version of the entire script if someone is willing to read and help. Dont want to post a long response otherwise. I have finished the script and it works as I intended but the help is lacking.

    by DexterPOSH at 2013-03-27 12:23:22

    It seems a bit odd and I don't even know what might be causing it.
    Did you tried seeing the help in some other machine than yours ?

    by DonJ at 2013-03-27 12:29:45

    As a quick note, if ANY of your comment-based help syntax is wrong, PowerShell won't use ANY of it. That's *usually* the cause when one function's help works, but another one's doesn't.

    by DexterPOSH at 2013-03-27 12:51:05

    [quote="DonJ"]As a quick note, if ANY of your comment-based help syntax is wrong, PowerShell won't use ANY of it. That's *usually* the cause when one function's help works, but another one's doesn't.[/quote]

    Thanks Don Sir.
    It never crossed mind as most of the time, I tend to use Snippets available in Script Editor to feed in the comment based help and just edit the required portions.

You must be logged in to reply to this topic.