Auto-documentation should document helper functions inside the Modules folder

[johlju]

It is hard for new and old contributors to know about the existing helper functions that are used to use the same patterns throughout the resources. It is not obvious for a contributor to first go through the module and read the comment-based help for each helper function to know what it does.

I would suggest automatically build Wiki documentation from each helper functions comment-based help. The .NOTES could be used to describe in what scenarios or patterns the helper function is meant to ease the logic (or whatever). But we could also have a README.md in the Modules folder that can be used for the start page for the helper functions Wiki documentation where we could describe the patterns (which can be different per resource module).

Goal is for everyone to use the same patterns and share new patterns.

[PlagueHO]

I like the approach here @johlju . Gets my vote.

[gaelcolas]

I'm still not sold on GitHub wiki. Much better than nothing for now, but I feel that'd be better 'pulled' by a documentation website of some sort, long term (i.e. from git hook). Can discuss this in a few weeks ;)

[PlagueHO]

I 100% agree with you @gaelcolas that we need to move to some form of documentation website. But this might have to do until some alternative comes along ;)

[johlju]

Agree, never been were fond of the GitHub Wiki since it is not easily discovered, but we could add the parsing logic to the test framework, and then it would easier to move it. Probably don't have time to work on it for a while though.

Suggest we using Get-Help -Detailed to get the full syntax of the parameter sets and examples as well. It should be simple thing looping through all the helper functions (cmdlets) exported from a module file and generate either one file with all with to ToC or separate files for each helper function.

PS > Get-Help Connect-SQL -Detailed

NAME
    Connect-SQL

SYNOPSIS
    Connect to a SQL Server Database Engine and return the server object.

SYNTAX
    Connect-SQL [-ServerName <String>] [-InstanceName <String>] [-StatementTimeout <Int32>] [<CommonParameters>]

    Connect-SQL [-ServerName <String>] [-InstanceName <String>] -SetupCredential <PSCredential> -LoginType <String> [-S
    tatementTimeout <Int32>] [<CommonParameters>]

DESCRIPTION

PARAMETERS
    -ServerName <String>

    -InstanceName <String>

    -SetupCredential <PSCredential>
        The credentials to use to impersonate a user when connecting to the
        SQL Server Database Engine instance. If this parameter is left out, then
        the current user will be used to connect to the SQL Server Database Engine
        instance using Windows Integrated authentication.

    -LoginType <String>
        Specifies which type of logon credential should be used. The valid types
        are WindowsUser or SqlLogin.
        If set to 'WindowsUser' then the it will impersonate using the Windows
        login specified in the parameter SetupCredential.
        If set to 'WindowsUser' then the it will impersonate using the native SQL
        login specified in the parameter SetupCredential.

    -StatementTimeout <Int32>
        Set the query StatementTimeout in seconds. Default 600 seconds (10 minutes).

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).

    -------------------------- EXAMPLE 1 --------------------------

    PS C:\>Connect-SQL

    Connects to the default instance on the local server.

    -------------------------- EXAMPLE 2 --------------------------

    PS C:\>Connect-SQL -InstanceName 'MyInstance'

    Connects to the instance 'MyInstance' on the local server.

    -------------------------- EXAMPLE 3 --------------------------

    PS C:\>Connect-SQL ServerName 'sql.company.local' -InstanceName 'MyInstance'

    Connects to the instance 'MyInstance' on the server 'sql.company.local'.

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