Auto-documentation should document helper functions inside the Modules folder #326

Activity

1. Johan Ljunggren (johlju)

   changed the title [-]Auto-documentation should document helper function in modules inside the Modules folder[/-] [+]Auto-documentation should document helper functions inside the Modules folder[/+] on Jun 16, 2019
2. Daniel Scott-Raynsford (PlagueHO)

   added

   enhancementThe issue is an enhancement request.The issue is an enhancement request.

   help wantedThe issue is up for grabs for anyone in the community.The issue is up for grabs for anyone in the community.

   on Jul 4, 2019
3. PlagueHO commented on Jul 4, 2019

   

   Daniel Scott-Raynsford (PlagueHO)

   on Jul 4, 2019

   Contributor

   More actions

   I like the approach here Johan Ljunggren (@johlju) . Gets my vote.
4. gaelcolas commented on Jul 4, 2019

   

   gaelcolas (gaelcolas)

   on Jul 4, 2019

   More actions

   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 ;)

   👍React with 👍1Reacted by Daniel Scott-Raynsford
5. PlagueHO commented on Jul 4, 2019

   

   Daniel Scott-Raynsford (PlagueHO)

   on Jul 4, 2019

   Contributor

   More actions

   I 100% agree with you gaelcolas (@gaelcolas) that we need to move to some form of documentation website. But this might have to do until some alternative comes along ;)
6. johlju commented on Jul 18, 2019

   

   Johan Ljunggren (johlju)

   on Jul 18, 2019

   ContributorAuthor

   More actions

   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".