-
Notifications
You must be signed in to change notification settings - Fork 14
Expand file tree
/
Copy pathNew-MBCommentBasedHelp.ps1
More file actions
109 lines (96 loc) · 4.21 KB
/
New-MBCommentBasedHelp.ps1
File metadata and controls
109 lines (96 loc) · 4.21 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
function New-MBCommentBasedHelp {
<#
.SYNOPSIS
Create comment based help for functions within a given scriptblock.
.DESCRIPTION
Create comment based help for functions within a given scriptblock.
.PARAMETER Code
Multi-line or piped lines of code to process.
.PARAMETER ScriptParameters
Process the script parameters as the source of the comment based help.
.EXAMPLE
PS > $testfile = 'C:\temp\test.ps1'
PS > $test = Get-Content $testfile -raw
PS > $test | New-MBCommentBasedHelp | clip
Takes C:\temp\test.ps1 as input, creates basic comment based help and puts the result in the clipboard
to be pasted elsewhere for review.
.EXAMPLE
PS > $CBH = Get-Content 'C:\EWSModule\Get-EWSContact.ps1' -Raw | New-MBTommentBasedHelp -Verbose
PS > ($CBH | Where {$FunctionName -eq 'Get-EWSContact'}).CBH
Consumes Get-EWSContact.ps1 and generates advanced CBH templates for all functions found within. Print out to the screen the advanced
CBH for just the Get-EWSContact function.
.NOTES
Author: Zachary Loeber
Site: http://www.the-little-things.net/
Requires: Powershell 3.0
Version History
1.0.0 - Initial release
1.0.1 - Updated for ModuleBuild
1.0.2 - Added SuppressMessageAttribute
1.0.3 - Extra Verbose message to check if function had Params
#>
[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseDeclaredVarsMoreThanAssignments", "ScriptText",Scope="Function",Target="New-MBCommentBasedHelp",Justification="Seems it's here since duo a copy paste from other functions (Add-MBMissingCBH,Get-MBFunction,Get-MBTFunctionParameter). Leaving it here since it doesn't do any harm.")]
[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions","",Scope="Function",Target="New-MBCommentBasedHelp",Justification="Function does not change system state. Simply outputs a obj with CommentBasedHelp.")]
[CmdletBinding()]
param(
[parameter(Position=0, ValueFromPipeline=$true, HelpMessage='Lines of code to process.')]
[string[]]$Code,
[parameter(Position=1, HelpMessage='Process the script parameters as the source of the comment based help.')]
[switch]$ScriptParameters
)
begin {
$FunctionName = $MyInvocation.MyCommand.Name
Write-Verbose "$($FunctionName): Begin."
$CBH_PARAM = @'
.PARAMETER %%PARAM%%
%%PARAMHELP%%
'@
$Codeblock = @()
$CBHTemplate = @'
<#
.SYNOPSIS
TBD
.DESCRIPTION
TBD
%%PARAMETER%% .EXAMPLE
TBD
#>
'@
}
process {
$Codeblock += $Code
}
end {
$ScriptText = ($Codeblock | Out-String).trim("`r`n")
Write-Verbose "$($FunctionName): Attempting to parse parameters."
$FuncParams = @{}
if ($ScriptParameters) {
$FuncParams.ScriptParameters = $true
}
$AllParams = Get-MBTFunctionParameter @FuncParams -Code $Codeblock | Sort-Object -Property FunctionName
$AllFunctions = @($AllParams.FunctionName | Select-Object -unique)
If([string]::IsNullOrEmpty($AllFunctions))
{
Write-Verbose "$($FunctionName): Found no Params in function."
} else
{
foreach ($f in $AllFunctions) {
$OutCBH = @{}
$OutCBH.FunctionName = $f
[string]$OutParams = ''
$fparams = @($AllParams | Where-Object {$_.FunctionName -eq $f} | Sort-Object -Property Position)
if ($fparams.count -gt 0) {
$fparams | ForEach-Object {
$ParamHelpMessage = if ([string]::IsNullOrEmpty($_.HelpMessage)) { $_.ParameterName + " explanation`n`r`n`r"} else {$_.HelpMessage + "`n`r`n`r"}
$OutParams += $CBH_PARAM -replace '%%PARAM%%',$_.ParameterName -replace '%%PARAMHELP%%',$ParamHelpMessage
}
}
else {
}
$OutCBH.'CBH' = $CBHTemplate -replace '%%PARAMETER%%',$OutParams
New-Object PSObject -Property $OutCBH
}
}
Write-Verbose "$($FunctionName): End."
}
}