From f7f952132d7ca2b7de62308be11563eeaa877f8a Mon Sep 17 00:00:00 2001 From: Matthew Martinez Date: Mon, 22 Jul 2019 15:55:35 +0300 Subject: [PATCH 1/5] add in a helper to create comment based help --- .../DscResourceCommentHelper.psm1 | 74 ++++++++ .../Get-DSCResourceParameters.psm1 | 164 ++++++++++++++++++ .../New-DscResourceCommentBasedHelp.psm1 | 85 +++++++++ 3 files changed, 323 insertions(+) create mode 100644 DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 create mode 100644 DscResource.DocumentationHelper/Get-DSCResourceParameters.psm1 create mode 100644 DscResource.DocumentationHelper/New-DscResourceCommentBasedHelp.psm1 diff --git a/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 b/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 new file mode 100644 index 00000000..58a61187 --- /dev/null +++ b/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 @@ -0,0 +1,74 @@ + +Function Get-ResourceFiles +{ + [CmdletBinding()] + param( + [Parameter(Mandatory=$true)] + [String] + $ResourceName + ) + + $returnFiles = @{ + SchemaFile = $null + ModuleFile = $null + } + + if (Test-Path -Path $ResourceName -ErrorAction SilentlyContinue) + { + if ($ResourceName -match '.*.schema.mof$') + { + $returnFiles.SchemaFile = $ResourceName + $returnFiles.ModuleFile = $ResourceName -replace '.schema.mof', '.psm1' + } + elseif ($ResourceName -match '.*.psm1$') + { + $returnFiles.SchemaFile = $ResourceName -replace '.psm1', '.schema.mof' + $returnFiles.ModuleFile = $ResourceName + } + elseif (Test-Path -Path $ResourceName -PathType Container) + { + # It's a directory, let's see if we can find the schema and psm files + $files = Get-ChildItem "C:\Users\martinezm\source\repos\xActiveDirectory\DSCResources\MSFT_xADKDSKey" + + $returnFiles.SchemaFile = ( + Get-ChildItem "C:\Users\martinezm\source\repos\xActiveDirectory\DSCResources\MSFT_xADKDSKey" -Filter *.schema.mof + ).FullName + + $returnFiles.ModuleFile = ( + Get-ChildItem "C:\Users\martinezm\source\repos\xActiveDirectory\DSCResources\MSFT_xADKDSKey" -Filter *.psm1 + ).FullName + + if ($returnFiles.SchemaFile -and $returnFiles.ModuleFile) + { + Write-Verbose ('Found the resource files in the directory "{0}"' -f $ResourceName) + } + else + { + throw ('Could not find the resource files in the directory "{0}"' -f $ResourceName) + } + } + else + { + throw ('The file "{0}" is an unrecognizable file type' -f $ResourceName) + } + + Write-Verbose ('Module found: {0}.' -f $ResourceName) + } + else + { + # The resource name may have been specified instead of the filename + if ($resourceInfo = Get-DscResource -Name $ResourceName -ErrorAction SilentlyContinue) + { + $returnFiles.SchemaFile = $resourceInfo.Path -replace '.psm1', '.schema.mof' + $returnFiles.ModuleFile = $resourceInfo.Path + } + else + { + throw ('Unable to get the information for the "{0}" resource.' -f $ResourceName) + } + } + + return $returnFiles +} + +Export-ModuleMember -Function * \ No newline at end of file diff --git a/DscResource.DocumentationHelper/Get-DSCResourceParameters.psm1 b/DscResource.DocumentationHelper/Get-DSCResourceParameters.psm1 new file mode 100644 index 00000000..94a21a50 --- /dev/null +++ b/DscResource.DocumentationHelper/Get-DSCResourceParameters.psm1 @@ -0,0 +1,164 @@ +<# +.SYNOPSIS + Get-DSCResourceParameters is used to get all the parameters that belong + to a specific DSC resource and a specific function in that resource. + +.DESCRIPTION + Uses AST to parse a DSC Resource module to get the parameters from it. + +.PARAMETER ResourceName + The resource module name or full path to the .psm1 file to process + +.PARAMETER FunctionNames + This gets the parameters for the functions inside the resource. + By default this would be: + 'Get-TargetResource', 'Test-TargetResource', 'Set-TargetResource' + +.OUTPUTS + This script will output a hashtable with the function and each parameter the + function has. @{} = [System.Management.Automation.Language.ParameterAst[]] + +.EXAMPLE + This example parses a psm1 file + + Get-DSCResourceParameters -ResourceName C:\DSC\MSFT_xAD\MSFT_xAD.psm1 + Get-DSCResourceParameters -ResourceName C:\DSC\MSFT_xAD\MSFT_xAD.psm1 ` + -FunctionName 'Get-TargetResource' + +#> +function Get-DSCResourceParameters +{ + [CmdletBinding()] + param( + [Parameter(Mandatory=$true)] + [String] + $ResourceName, + + [String[]] + $FunctionNames = @( + 'Get-TargetResource' + 'Test-TargetResource' + 'Set-TargetResource' + ) + ) + + Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath 'DscResourceCommentHelper.psm1') + $resourceFiles = Get-ResourceFiles $ResourceName + + $resourceAST = ConvertTo-ParsedAST -ResourceName $resourceFiles.ModuleFile + + Write-Verbose ('Parsing functions: {0}' -f ($FunctionNames -join ', ')) + $functionDefinitionAst = $resourceAST.FindAll( + { + param($Item) + return ( + $Item -is [System.Management.Automation.Language.FunctionDefinitionAst] -And + $Item.Name -in $FunctionNames + ) + }, + $true + ) + + # Check if we found all the functions, if not, show warning + if ($functionDefinitionAst.Count -lt 1) + { + throw ('Could not find any of functions: "{0}" in the resource "{1}"' -f ($FunctionNames -join ','), $ResourceName) + } + else + { + $missingFunctions = Compare-Object -ReferenceObject $FunctionNames -DifferenceObject $functionDefinitionAst.Name + $foundFunctions = Compare-Object -ReferenceObject $FunctionNames -DifferenceObject $functionDefinitionAst.Name -IncludeEqual -ExcludeDifferent + if ($missingFunctions) + { + Write-Warning ( + 'Could not find the following functions: [{0}], but will continue with the ones we did find: [{1}]' -f ( + ($missingFunctions.InputObject -join ', '), + ($foundFunctions.InputObject -join ', ') + ) + ) + } + } + + Write-Verbose 'Parsing parameters for each function' + $parameterDictionary = @{} + $functionDefinitionAst | ForEach-Object { + $functionName = $PSItem.Name + Write-Verbose ('Attempting to find the parameters for the "{0}" function' -f $functionName) + $parameterDictionary[$functionName] = @() + + $functionParameters = $PSItem.Find( + { + param($Item) + return ( + $Item -is [System.Management.Automation.Language.ParamBlockAst] + ) + }, + $true + ) + + if ($functionParameters.Count -lt 1) + { + Write-Error 'No parameters found for "{0}"' -f $functionName + continue + } + + $parameterDictionary[$functionName] = $functionParameters.Parameters + } + + return $parameterDictionary +} + +<# +.SYNOPSIS + ConvertTo-ParsedAST + +.DESCRIPTION + This will check if the resource file is specified and if not, it will get + the file from the resource name + +.PARAMETER ResourceName + The resource module name or full path to the .psm1 file to process + +.OUTPUTS + This script will output an AST parsed file + +#> +Function ConvertTo-ParsedAST +{ + [CmdletBinding()] + param( + [Parameter(Mandatory=$true)] + [String] + $ResourceName + ) + + $getModuleParameters = @{ + Name = $ResourceName + ListAvailable = $True + } + + $parseErrors = $null + $astResourceParsed = $null + Write-Verbose ('Retreiving module information for: {0}.' -f $getModuleParameters.Name) + if ($moduleInfo = Get-Module @getModuleParameters) + { + $astResourceParsed = [System.Management.Automation.Language.Parser]::ParseFile( + $getModuleParameters.Name, [ref] $null, [ref] $parseErrors + ) + } + else + { + throw ('Unable to get the information for the "{0}" resource.' -f $ResourceName) + } + + if ($parseErrors.Count -ne 0) { + throw ( + 'Parsing errors detected when parsing file: {0} | {1}' -f $getModuleParameters.Name, $parseErrors + ) + } + + return $astResourceParsed +} + + +Export-ModuleMember -Function Get-DSCResourceParameters \ No newline at end of file diff --git a/DscResource.DocumentationHelper/New-DscResourceCommentBasedHelp.psm1 b/DscResource.DocumentationHelper/New-DscResourceCommentBasedHelp.psm1 new file mode 100644 index 00000000..5fdb1bfa --- /dev/null +++ b/DscResource.DocumentationHelper/New-DscResourceCommentBasedHelp.psm1 @@ -0,0 +1,85 @@ +<# +.SYNOPSIS + New-DscResourceCommentBasedHelp will generate the comment based help based + on the parameters and mof schema + +.DESCRIPTION + New-DscResourceCommentBasedHelp will parse the MOF schema file and compare + that to the function within the DSC resource and then generate a comment + based help section to place before the Function. This will take the + descriptions from the mof and add them as parameters and a description for + each parameter that is used in the function. The only thing it won't be able + to do is add a SYNOPSIS statement + +.PARAMETER ResourceName + The resource module name or full path to the .psm1 or mof file to process. + This can be the directory where the .psm1 or .mof file resides or one of the + files themselves. This can also be the resource name if the resource is + installed on the computer + +.PARAMETER FunctionNames + This gets the parameters for the functions inside the resource. + By default this would be: + 'Get-TargetResource', 'Test-TargetResource', 'Set-TargetResource' + +.OUTPUTS + This script will output a multi-line string with .SYNOPSIS and + each .PARAMETER value + +.EXAMPLE + This example parses a psm1 file + + New-DscResourceCommentBasedHelp -ResourceName C:\DSC\MSFT_xAD\MSFT_xAD.psm1 + New-DscResourceCommentBasedHelp -ResourceName C:\DSC\MSFT_xAD\MSFT_xAD.mof + New-DscResourceCommentBasedHelp -ResourceName C:\DSC\MSFT_xAD + Get-DSCResourceParameters -ResourceName C:\DSC\MSFT_xAD\MSFT_xAD.psm1 ` + -FunctionName 'Get-TargetResource' + +#> +Function New-DscResourceCommentBasedHelp +{ + [CmdletBinding()] + param( + [Parameter(Mandatory=$true)] + [String] + $ResourceName, + + [String[]] + $FunctionNames = @( + 'Get-TargetResource' + 'Test-TargetResource' + 'Set-TargetResource' + ) + ) + + Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath 'MofHelper.psm1') + Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath 'Get-DSCResourceParameters.psm1') + Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath 'DscResourceCommentHelper.psm1') + + $resourceFiles = Get-ResourceFiles $ResourceName + + $moduleParameters = Get-DSCResourceParameters $resourceFiles.ModuleFile + $schemaParameters = Get-MofSchemaObject -FileName $resourceFiles.SchemaFile + + $outputStrings = @{} + + foreach($function in $moduleParameters.Keys){ + Write-Verbose ('Creating the comment help based section for the function {0}' -f $function) + $output = New-Object -TypeName System.Text.StringBuilder + $null = $output.Append("<# ").AppendLine($function) + $null = $output.AppendLine(" .SYNOPSIS") + $null = $output.AppendLine(" Add Synopsis here`n") + + foreach($parameter in $moduleParameters[$function]){ + $parameterName = $parameter.Name.VariablePath.UserPath + $getMOFParameter = $schemaParameters.Attributes | Where-Object {$_.Name -eq $parameterName} + $null = $output.Append(" .PARAMETER ").AppendLine($parameterName) + $null = $output.AppendLine(" $($getMOFParameter.Description)`n") + } + + $null = $output.AppendLine("#>") + $outputStrings[$function] = $output.ToString() + } + + $outputStrings +} \ No newline at end of file From 60242e843124bbf2c2bdd8261a03e856c76bf332 Mon Sep 17 00:00:00 2001 From: Matthew Martinez Date: Tue, 23 Jul 2019 08:54:39 +0300 Subject: [PATCH 2/5] Added localized strings and fixed some formatting --- .../DscResourceCommentHelper.psm1 | 116 +++++++++++------- .../Get-DSCResourceParameters.psm1 | 10 +- .../New-DscResourceCommentBasedHelp.psm1 | 59 ++++++--- .../DscResourceCommentHelper.strings.psd1 | 7 ++ .../Get-DSCResourceParameters.strings.psd1 | 0 ...w-DscResourceCommentBasedHelp.strings.psd1 | 0 6 files changed, 126 insertions(+), 66 deletions(-) create mode 100644 DscResource.DocumentationHelper/en-US/DscResourceCommentHelper.strings.psd1 create mode 100644 DscResource.DocumentationHelper/en-US/Get-DSCResourceParameters.strings.psd1 create mode 100644 DscResource.DocumentationHelper/en-US/New-DscResourceCommentBasedHelp.strings.psd1 diff --git a/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 b/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 index 58a61187..744f92e8 100644 --- a/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 +++ b/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 @@ -1,4 +1,37 @@ +$projectRootPath = Split-Path -Path $PSScriptRoot -Parent +$testHelperPath = Join-Path -Path $projectRootPath -ChildPath 'TestHelper.psm1' +Import-Module -Name $testHelperPath -Force + +$script:localizedData = Get-LocalizedData -ModuleName 'DscResourceCommentHelper' -ModuleRoot $PSScriptRoot + + +<# +.SYNOPSIS + Get-ResourceFiles will get the mof and module file for a specified resource + +.DESCRIPTION + This will look for the files necassary for a dsc resource and return the + location of those files. This is mainly used when the files are required for + parsing and metadata is needed + +.PARAMETER ResourceName + The resource module name, path to the .psm1, path to the .mof, or the + directory to process + +.OUTPUTS + This script will output a hashtable with SchemaFile and ModuleFile + @{ + SchemaFile + ModuleFile + } + +.EXAMPLE + This example parses a psm1 file and returns both the schema and mof file + + Get-ResourceFiles -ResourceName C:\DSC\MSFT_xAD\MSFT_xAD.psm1 + +#> Function Get-ResourceFiles { [CmdletBinding()] @@ -8,67 +41,64 @@ Function Get-ResourceFiles $ResourceName ) - $returnFiles = @{ - SchemaFile = $null - ModuleFile = $null - } - - if (Test-Path -Path $ResourceName -ErrorAction SilentlyContinue) + if ($ResourceName -match '.*.schema.mof$' -or $ResourceName -match '.*.psm1$') { - if ($ResourceName -match '.*.schema.mof$') + if (Test-Path -Path $ResourceName -ErrorAction SilentlyContinue) { - $returnFiles.SchemaFile = $ResourceName - $returnFiles.ModuleFile = $ResourceName -replace '.schema.mof', '.psm1' + + return @{ + SchemaFile = $ResourceName -replace '.psm1', '.schema.mof' + ModuleFile = $ResourceName -replace '.schema.mof', '.psm1' + } } - elseif ($ResourceName -match '.*.psm1$') + else { - $returnFiles.SchemaFile = $ResourceName -replace '.psm1', '.schema.mof' - $returnFiles.ModuleFile = $ResourceName + throw ($script:localizedData.ResourceFileNotFound -f $ResourceName) } - elseif (Test-Path -Path $ResourceName -PathType Container) - { - # It's a directory, let's see if we can find the schema and psm files - $files = Get-ChildItem "C:\Users\martinezm\source\repos\xActiveDirectory\DSCResources\MSFT_xADKDSKey" + } + + if (Test-Path -Path $ResourceName -PathType Container) + { + # It's a directory, let's see if we can find the schema and psm files + $files = Get-ChildItem $ResourceName - $returnFiles.SchemaFile = ( - Get-ChildItem "C:\Users\martinezm\source\repos\xActiveDirectory\DSCResources\MSFT_xADKDSKey" -Filter *.schema.mof + $returnFiles = @{ + + SchemaFile = ( + Get-ChildItem $ResourceName -Filter *.schema.mof ).FullName - $returnFiles.ModuleFile = ( - Get-ChildItem "C:\Users\martinezm\source\repos\xActiveDirectory\DSCResources\MSFT_xADKDSKey" -Filter *.psm1 + ModuleFile = ( + Get-ChildItem $ResourceName -Filter *.psm1 ).FullName + } - if ($returnFiles.SchemaFile -and $returnFiles.ModuleFile) - { - Write-Verbose ('Found the resource files in the directory "{0}"' -f $ResourceName) - } - else - { - throw ('Could not find the resource files in the directory "{0}"' -f $ResourceName) - } + if ($returnFiles.SchemaFile -and $returnFiles.ModuleFile) + { + Write-Verbose ( + $script:localizedData.ResourceFilesFound -f $ResourceName + ) + + return $returnFiles } else { - throw ('The file "{0}" is an unrecognizable file type' -f $ResourceName) + throw ( + $script:localizedData.ResourceFilesNotFoundInDirectory -f $ResourceName + ) } - - Write-Verbose ('Module found: {0}.' -f $ResourceName) } - else + + # The resource name may have been specified instead of the filename or directory + if ($resourceInfo = Get-DscResource -Name $ResourceName -ErrorAction SilentlyContinue) { - # The resource name may have been specified instead of the filename - if ($resourceInfo = Get-DscResource -Name $ResourceName -ErrorAction SilentlyContinue) - { - $returnFiles.SchemaFile = $resourceInfo.Path -replace '.psm1', '.schema.mof' - $returnFiles.ModuleFile = $resourceInfo.Path - } - else - { - throw ('Unable to get the information for the "{0}" resource.' -f $ResourceName) + return @{ + SchemaFile = $resourceInfo.Path -replace '.psm1', '.schema.mof' + ModuleFile = $resourceInfo.Path } } - return $returnFiles + throw ($script:localizedData.ResourceInfoError -f $ResourceName) } -Export-ModuleMember -Function * \ No newline at end of file +Export-ModuleMember -Function * diff --git a/DscResource.DocumentationHelper/Get-DSCResourceParameters.psm1 b/DscResource.DocumentationHelper/Get-DSCResourceParameters.psm1 index 94a21a50..d0964e4f 100644 --- a/DscResource.DocumentationHelper/Get-DSCResourceParameters.psm1 +++ b/DscResource.DocumentationHelper/Get-DSCResourceParameters.psm1 @@ -139,7 +139,9 @@ Function ConvertTo-ParsedAST $parseErrors = $null $astResourceParsed = $null - Write-Verbose ('Retreiving module information for: {0}.' -f $getModuleParameters.Name) + Write-Verbose ('Retreiving module information for: {0}.' -f ` + $getModuleParameters.Name) + if ($moduleInfo = Get-Module @getModuleParameters) { $astResourceParsed = [System.Management.Automation.Language.Parser]::ParseFile( @@ -148,12 +150,14 @@ Function ConvertTo-ParsedAST } else { - throw ('Unable to get the information for the "{0}" resource.' -f $ResourceName) + throw ('Unable to get the information for the "{0}" resource.' ` + -f $ResourceName) } if ($parseErrors.Count -ne 0) { throw ( - 'Parsing errors detected when parsing file: {0} | {1}' -f $getModuleParameters.Name, $parseErrors + 'Parsing errors detected when parsing file: {0} | {1}' ` + -f $getModuleParameters.Name, $parseErrors ) } diff --git a/DscResource.DocumentationHelper/New-DscResourceCommentBasedHelp.psm1 b/DscResource.DocumentationHelper/New-DscResourceCommentBasedHelp.psm1 index 5fdb1bfa..8c4b7831 100644 --- a/DscResource.DocumentationHelper/New-DscResourceCommentBasedHelp.psm1 +++ b/DscResource.DocumentationHelper/New-DscResourceCommentBasedHelp.psm1 @@ -23,8 +23,8 @@ 'Get-TargetResource', 'Test-TargetResource', 'Set-TargetResource' .OUTPUTS - This script will output a multi-line string with .SYNOPSIS and - each .PARAMETER value + This script will output a hash table with multi-line string that include + an empty .SYNOPSIS and each .PARAMETER value .EXAMPLE This example parses a psm1 file @@ -52,34 +52,53 @@ Function New-DscResourceCommentBasedHelp ) ) - Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath 'MofHelper.psm1') - Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath 'Get-DSCResourceParameters.psm1') - Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath 'DscResourceCommentHelper.psm1') + Import-Module -Name ( + Join-Path -Path $PSScriptRoot -ChildPath 'MofHelper.psm1' + ) + + Import-Module -Name ( + Join-Path -Path $PSScriptRoot -ChildPath 'Get-DSCResourceParameters.psm1' + ) + + Import-Module -Name ( + Join-Path -Path $PSScriptRoot -ChildPath 'DscResourceCommentHelper.psm1' + ) $resourceFiles = Get-ResourceFiles $ResourceName $moduleParameters = Get-DSCResourceParameters $resourceFiles.ModuleFile $schemaParameters = Get-MofSchemaObject -FileName $resourceFiles.SchemaFile - $outputStrings = @{} - + $outputStringsForEachFunction = @{} + $tab = [System.String]::new(' ',4) foreach($function in $moduleParameters.Keys){ - Write-Verbose ('Creating the comment help based section for the function {0}' -f $function) - $output = New-Object -TypeName System.Text.StringBuilder - $null = $output.Append("<# ").AppendLine($function) - $null = $output.AppendLine(" .SYNOPSIS") - $null = $output.AppendLine(" Add Synopsis here`n") + Write-Verbose ( + 'Creating the comment help based section for the function {0}' -f $function + ) + + $stringBuilder = New-Object -TypeName System.Text.StringBuilder - foreach($parameter in $moduleParameters[$function]){ + # Start Synopsis + $null = $stringBuilder.AppendLine('<#') + $null = $stringBuilder.AppendLine($tab + '.SYNOPSIS') + $null = $stringBuilder.AppendLine($tab + $tab + 'Synopsis here') + $null = $stringBuilder.AppendLine('') + + # Add each parameter + foreach($parameter in $moduleParameters[$function]){ $parameterName = $parameter.Name.VariablePath.UserPath - $getMOFParameter = $schemaParameters.Attributes | Where-Object {$_.Name -eq $parameterName} - $null = $output.Append(" .PARAMETER ").AppendLine($parameterName) - $null = $output.AppendLine(" $($getMOFParameter.Description)`n") - } + $getMOFParameter = $schemaParameters.Attributes | Where-Object { + $_.Name -eq $parameterName + } + + $null = $stringBuilder.AppendLine($tab + '.PARAMETER ' + $parameterName) + $null = $stringBuilder.AppendLine($tab + $tab + $getMOFParameter.Description) + $null = $stringBuilder.AppendLine('') + } - $null = $output.AppendLine("#>") - $outputStrings[$function] = $output.ToString() + $null = $stringBuilder.AppendLine("#>") + $outputStringsForEachFunction[$function] = $stringBuilder.ToString() } - $outputStrings + return $outputStringsForEachFunction } \ No newline at end of file diff --git a/DscResource.DocumentationHelper/en-US/DscResourceCommentHelper.strings.psd1 b/DscResource.DocumentationHelper/en-US/DscResourceCommentHelper.strings.psd1 new file mode 100644 index 00000000..43c030d7 --- /dev/null +++ b/DscResource.DocumentationHelper/en-US/DscResourceCommentHelper.strings.psd1 @@ -0,0 +1,7 @@ +# culture="en-US" +ConvertFrom-StringData @' + ResourceFileNotFound = The following file '{0}' does not exist, please verify that the file location is correct. + ResourceFilesNotFoundInDirectory = Could not find the resource files in the directory '{0}, please verify that the location is correct.' + ResourceFilesFound = The resource files exist in the directory '{0}.' + ResourceInfoError = Could not retrieve the information for the resource '{0}, please verify that the resource exists.' +'@ diff --git a/DscResource.DocumentationHelper/en-US/Get-DSCResourceParameters.strings.psd1 b/DscResource.DocumentationHelper/en-US/Get-DSCResourceParameters.strings.psd1 new file mode 100644 index 00000000..e69de29b diff --git a/DscResource.DocumentationHelper/en-US/New-DscResourceCommentBasedHelp.strings.psd1 b/DscResource.DocumentationHelper/en-US/New-DscResourceCommentBasedHelp.strings.psd1 new file mode 100644 index 00000000..e69de29b From b0c0eebc25367491ebf7b6b779c7dab60473db46 Mon Sep 17 00:00:00 2001 From: Matthew Martinez Date: Tue, 23 Jul 2019 11:12:28 +0300 Subject: [PATCH 3/5] Fixed some more styling issues and added in more messaging --- .../DscResourceCommentHelper.psm1 | 2 +- .../Get-DSCResourceParameters.psm1 | 61 +++++++++++++------ .../New-DscResourceCommentBasedHelp.psm1 | 17 ++++-- .../DscResourceCommentHelper.strings.psd1 | 6 +- .../Get-DSCResourceParameters.strings.psd1 | 12 ++++ ...w-DscResourceCommentBasedHelp.strings.psd1 | 4 ++ 6 files changed, 76 insertions(+), 26 deletions(-) diff --git a/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 b/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 index 744f92e8..921ca679 100644 --- a/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 +++ b/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 @@ -75,7 +75,7 @@ Function Get-ResourceFiles if ($returnFiles.SchemaFile -and $returnFiles.ModuleFile) { - Write-Verbose ( + Write-Verbose -Message ( $script:localizedData.ResourceFilesFound -f $ResourceName ) diff --git a/DscResource.DocumentationHelper/Get-DSCResourceParameters.psm1 b/DscResource.DocumentationHelper/Get-DSCResourceParameters.psm1 index d0964e4f..e35a34a4 100644 --- a/DscResource.DocumentationHelper/Get-DSCResourceParameters.psm1 +++ b/DscResource.DocumentationHelper/Get-DSCResourceParameters.psm1 @@ -1,3 +1,10 @@ + +$projectRootPath = Split-Path -Path $PSScriptRoot -Parent +$testHelperPath = Join-Path -Path $projectRootPath -ChildPath 'TestHelper.psm1' +Import-Module -Name $testHelperPath -Force + +$script:localizedData = Get-LocalizedData -ModuleName 'Get-DSCResourceParameters' -ModuleRoot $PSScriptRoot + <# .SYNOPSIS Get-DSCResourceParameters is used to get all the parameters that belong @@ -42,12 +49,16 @@ function Get-DSCResourceParameters ) ) - Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath 'DscResourceCommentHelper.psm1') + Import-Module -Name ( + Join-Path -Path $PSScriptRoot -ChildPath 'DscResourceCommentHelper.psm1' + ) $resourceFiles = Get-ResourceFiles $ResourceName $resourceAST = ConvertTo-ParsedAST -ResourceName $resourceFiles.ModuleFile - Write-Verbose ('Parsing functions: {0}' -f ($FunctionNames -join ', ')) + Write-Verbose -Message ( + $script:localizedData.VerboseParsingFunctions -f ($FunctionNames -join ', ') + ) $functionDefinitionAst = $resourceAST.FindAll( { param($Item) @@ -62,16 +73,24 @@ function Get-DSCResourceParameters # Check if we found all the functions, if not, show warning if ($functionDefinitionAst.Count -lt 1) { - throw ('Could not find any of functions: "{0}" in the resource "{1}"' -f ($FunctionNames -join ','), $ResourceName) + throw ( + $script:localizedData.DidNotFindAnyFunctions -f ( + $FunctionNames -join ',' + ), $ResourceName + ) } else { - $missingFunctions = Compare-Object -ReferenceObject $FunctionNames -DifferenceObject $functionDefinitionAst.Name - $foundFunctions = Compare-Object -ReferenceObject $FunctionNames -DifferenceObject $functionDefinitionAst.Name -IncludeEqual -ExcludeDifferent + $compareParameters = @{ + ReferenceObject = $FunctionNames + DifferenceObject = $functionDefinitionAst.Name + } + $missingFunctions = Compare-Object @compareParameters + $foundFunctions = Compare-Object @compareParameters -IncludeEqual -ExcludeDifferent if ($missingFunctions) { - Write-Warning ( - 'Could not find the following functions: [{0}], but will continue with the ones we did find: [{1}]' -f ( + Write-Warning -Message ( + $script:localizedData.DidNotFindFunction -f ( ($missingFunctions.InputObject -join ', '), ($foundFunctions.InputObject -join ', ') ) @@ -79,11 +98,18 @@ function Get-DSCResourceParameters } } - Write-Verbose 'Parsing parameters for each function' + Write-Verbose -Message ( + $script:localizedData.VerboseParsingParameters -f ( + $foundFunctions.InputObject -join ', ' + ) + ) $parameterDictionary = @{} $functionDefinitionAst | ForEach-Object { $functionName = $PSItem.Name - Write-Verbose ('Attempting to find the parameters for the "{0}" function' -f $functionName) + Write-Verbose -Message ( + $script:localizedData.VerboseFindParameters -f $functionName + ) + $parameterDictionary[$functionName] = @() $functionParameters = $PSItem.Find( @@ -98,7 +124,9 @@ function Get-DSCResourceParameters if ($functionParameters.Count -lt 1) { - Write-Error 'No parameters found for "{0}"' -f $functionName + Write-Error -Message ( + $script:localizedData.NoParametersFound -f $functionName + ) continue } @@ -139,8 +167,9 @@ Function ConvertTo-ParsedAST $parseErrors = $null $astResourceParsed = $null - Write-Verbose ('Retreiving module information for: {0}.' -f ` - $getModuleParameters.Name) + Write-Verbose -Message ( + $script:localizedData.GetModuleInfo -f $getModuleParameters.Name + ) if ($moduleInfo = Get-Module @getModuleParameters) { @@ -150,14 +179,12 @@ Function ConvertTo-ParsedAST } else { - throw ('Unable to get the information for the "{0}" resource.' ` - -f $ResourceName) + throw ($script:localizedData.ErrorGetModuleInfo -f $ResourceName) } if ($parseErrors.Count -ne 0) { throw ( - 'Parsing errors detected when parsing file: {0} | {1}' ` - -f $getModuleParameters.Name, $parseErrors + $script:localizedData.ErrorParseAST -f $getModuleParameters.Name, $parseErrors ) } @@ -165,4 +192,4 @@ Function ConvertTo-ParsedAST } -Export-ModuleMember -Function Get-DSCResourceParameters \ No newline at end of file +Export-ModuleMember -Function Get-DSCResourceParameters diff --git a/DscResource.DocumentationHelper/New-DscResourceCommentBasedHelp.psm1 b/DscResource.DocumentationHelper/New-DscResourceCommentBasedHelp.psm1 index 8c4b7831..dc110453 100644 --- a/DscResource.DocumentationHelper/New-DscResourceCommentBasedHelp.psm1 +++ b/DscResource.DocumentationHelper/New-DscResourceCommentBasedHelp.psm1 @@ -1,3 +1,10 @@ + +$projectRootPath = Split-Path -Path $PSScriptRoot -Parent +$testHelperPath = Join-Path -Path $projectRootPath -ChildPath 'TestHelper.psm1' +Import-Module -Name $testHelperPath -Force + +$script:localizedData = Get-LocalizedData -ModuleName 'New-DscResourceCommentBasedHelp' -ModuleRoot $PSScriptRoot + <# .SYNOPSIS New-DscResourceCommentBasedHelp will generate the comment based help based @@ -68,12 +75,12 @@ Function New-DscResourceCommentBasedHelp $moduleParameters = Get-DSCResourceParameters $resourceFiles.ModuleFile $schemaParameters = Get-MofSchemaObject -FileName $resourceFiles.SchemaFile - + $outputStringsForEachFunction = @{} $tab = [System.String]::new(' ',4) foreach($function in $moduleParameters.Keys){ - Write-Verbose ( - 'Creating the comment help based section for the function {0}' -f $function + Write-Verbose -Message ( + $script:localizedData.VerboseFunctionComments -f $function ) $stringBuilder = New-Object -TypeName System.Text.StringBuilder @@ -88,7 +95,7 @@ Function New-DscResourceCommentBasedHelp foreach($parameter in $moduleParameters[$function]){ $parameterName = $parameter.Name.VariablePath.UserPath $getMOFParameter = $schemaParameters.Attributes | Where-Object { - $_.Name -eq $parameterName + $PSItem.Name -eq $parameterName } $null = $stringBuilder.AppendLine($tab + '.PARAMETER ' + $parameterName) @@ -101,4 +108,4 @@ Function New-DscResourceCommentBasedHelp } return $outputStringsForEachFunction -} \ No newline at end of file +} diff --git a/DscResource.DocumentationHelper/en-US/DscResourceCommentHelper.strings.psd1 b/DscResource.DocumentationHelper/en-US/DscResourceCommentHelper.strings.psd1 index 43c030d7..5165b7f9 100644 --- a/DscResource.DocumentationHelper/en-US/DscResourceCommentHelper.strings.psd1 +++ b/DscResource.DocumentationHelper/en-US/DscResourceCommentHelper.strings.psd1 @@ -1,7 +1,7 @@ # culture="en-US" ConvertFrom-StringData @' ResourceFileNotFound = The following file '{0}' does not exist, please verify that the file location is correct. - ResourceFilesNotFoundInDirectory = Could not find the resource files in the directory '{0}, please verify that the location is correct.' - ResourceFilesFound = The resource files exist in the directory '{0}.' - ResourceInfoError = Could not retrieve the information for the resource '{0}, please verify that the resource exists.' + ResourceFilesNotFoundInDirectory = Could not find the resource files in the directory '{0}', please verify that the location is correct. + ResourceFilesFound = The resource files exist in the directory '{0}'. + ResourceInfoError = Could not retrieve the information for the resource '{0}', please verify that the resource exists. '@ diff --git a/DscResource.DocumentationHelper/en-US/Get-DSCResourceParameters.strings.psd1 b/DscResource.DocumentationHelper/en-US/Get-DSCResourceParameters.strings.psd1 index e69de29b..e1e4ff15 100644 --- a/DscResource.DocumentationHelper/en-US/Get-DSCResourceParameters.strings.psd1 +++ b/DscResource.DocumentationHelper/en-US/Get-DSCResourceParameters.strings.psd1 @@ -0,0 +1,12 @@ +# culture="en-US" +ConvertFrom-StringData @' + VerboseParsingFunctions = Attempting to parse the specified functions: [{0}]. + VerboseParsingParameters = Attempting to parse the parameters for each function: [{0}]. + VerboseFindParameters = Attempting to parse the parameters for the '{0}' function. + DidNotFindAnyFunctions = Could not find the any of the functions specified [{0}] in the resource '{1}'. + DidNotFindFunction = Could not find the following functions: [{0}], but will continue with the ones that were found: [{1}] + NoParametersFound = Could not find any parameters for the function '{0}'. + GetModuleInfo = Retreiving module information for: '{0}'. + ErrorGetModuleInfo = Unable to module information for the resource: '{0}'. + ErrorParseAST = There were errors when attempting to parse the module file '{0}' | {1}. +'@ diff --git a/DscResource.DocumentationHelper/en-US/New-DscResourceCommentBasedHelp.strings.psd1 b/DscResource.DocumentationHelper/en-US/New-DscResourceCommentBasedHelp.strings.psd1 index e69de29b..2eeaf6d2 100644 --- a/DscResource.DocumentationHelper/en-US/New-DscResourceCommentBasedHelp.strings.psd1 +++ b/DscResource.DocumentationHelper/en-US/New-DscResourceCommentBasedHelp.strings.psd1 @@ -0,0 +1,4 @@ +# culture="en-US" +ConvertFrom-StringData @' + VerboseFunctionComments = Creating the comment help based section for the function '{0}'. +'@ From f30b8af836ebf69b656fe11fb5ca19d3d82f7512 Mon Sep 17 00:00:00 2001 From: Matthew Martinez Date: Wed, 24 Jul 2019 09:41:24 +0300 Subject: [PATCH 4/5] Combined all helper functions into one module. Added comment helper parser to add back comments that already exist --- .../DscResourceCommentHelper.psm1 | 294 +++++++++++++++++- .../Get-DSCResourceParameters.psm1 | 195 ------------ .../New-DscResourceCommentBasedHelp.psm1 | 15 +- .../DscResourceCommentHelper.strings.psd1 | 7 - 4 files changed, 299 insertions(+), 212 deletions(-) delete mode 100644 DscResource.DocumentationHelper/Get-DSCResourceParameters.psm1 delete mode 100644 DscResource.DocumentationHelper/en-US/DscResourceCommentHelper.strings.psd1 diff --git a/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 b/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 index 921ca679..a4e3eeab 100644 --- a/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 +++ b/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 @@ -5,7 +5,6 @@ Import-Module -Name $testHelperPath -Force $script:localizedData = Get-LocalizedData -ModuleName 'DscResourceCommentHelper' -ModuleRoot $PSScriptRoot - <# .SYNOPSIS Get-ResourceFiles will get the mof and module file for a specified resource @@ -101,4 +100,297 @@ Function Get-ResourceFiles throw ($script:localizedData.ResourceInfoError -f $ResourceName) } +<# +.SYNOPSIS + Get-DSCResourceParameters is used to get all the parameters that belong + to a specific DSC resource and a specific function in that resource. + +.DESCRIPTION + Uses AST to parse a DSC Resource module to get the parameters from it. + +.PARAMETER ResourceName + The resource module name or full path to the .psm1 file to process + +.PARAMETER FunctionNames + This gets the parameters for the functions inside the resource. + By default this would be: + 'Get-TargetResource', 'Test-TargetResource', 'Set-TargetResource' + +.OUTPUTS + This script will output a hashtable with the function and each parameter the + function has. @{} = [System.Management.Automation.Language.ParameterAst[]] + +.EXAMPLE + This example parses a psm1 file + + Get-DSCResourceParameters -ResourceName C:\DSC\MSFT_xAD\MSFT_xAD.psm1 + Get-DSCResourceParameters -ResourceName C:\DSC\MSFT_xAD\MSFT_xAD.psm1 ` + -FunctionName 'Get-TargetResource' + +#> +function Get-DSCResourceParameters +{ + [CmdletBinding()] + param( + [Parameter(Mandatory=$true)] + [String] + $ResourceName, + + [String[]] + $FunctionNames = @( + 'Get-TargetResource' + 'Test-TargetResource' + 'Set-TargetResource' + ) + ) + $resourceFiles = Get-ResourceFiles $ResourceName + + $resourceAST = ConvertTo-ParsedAST -ResourceName $resourceFiles.ModuleFile + + Write-Verbose -Message ( + $script:localizedData.VerboseParsingFunctions -f ($FunctionNames -join ', ') + ) + + $functionDefinitionAst = Get-DSCResourceFunctionsFromAST -Ast $resourceAST -FunctionNames $FunctionNames + + Write-Verbose -Message ( + $script:localizedData.VerboseParsingParameters -f ( + $foundFunctions.InputObject -join ', ' + ) + ) + $parameterDictionary = @{} + # Go through each function and add the parameters for that function + $functionDefinitionAst | ForEach-Object { + $functionName = $PSItem.Name + Write-Verbose -Message ( + $script:localizedData.VerboseFindParameters -f $functionName + ) + + $parameterDictionary[$functionName] = @() + + $functionParameters = $PSItem.Find( + { + param($Item) + return ( + $Item -is [System.Management.Automation.Language.ParamBlockAst] + ) + }, + $true + ) + + if ($functionParameters.Count -lt 1) + { + Write-Error -Message ( + $script:localizedData.NoParametersFound -f $functionName + ) + continue + } + + $parameterDictionary[$functionName] = $functionParameters.Parameters + } + + return $parameterDictionary +} + +<# +.SYNOPSIS + Get-DSCResourceCommentBasedHelp is used to get all the help based comments + that belong to a specific DSC resource and a specific function in that + resource. + +.DESCRIPTION + Uses AST to parse a DSC Resource module to get the help based comments + from it. + +.PARAMETER ResourceName + The resource module name or full path to the .psm1 file to process + +.PARAMETER FunctionNames + This gets the parameters for the functions inside the resource. + By default this would be: + 'Get-TargetResource', 'Test-TargetResource', 'Set-TargetResource' + +.OUTPUTS + This script will output a hashtable with the function and each comment + object the function has. @{} = [System.Object] + +.EXAMPLE + This example parses a psm1 file + + Get-DSCResourceCommentBasedHelp -ResourceName C:\DSC\MSFT_xAD\MSFT_xAD.psm1 + Get-DSCResourceCommentBasedHelp -ResourceName C:\DSC\MSFT_xAD\MSFT_xAD.psm1 ` + -FunctionName 'Get-TargetResource' + +#> +function Get-DSCResourceCommentBasedHelp +{ + [CmdletBinding()] + param( + [Parameter(Mandatory=$true)] + [String] + $ResourceName, + + [String[]] + $FunctionNames = @( + 'Get-TargetResource' + 'Test-TargetResource' + 'Set-TargetResource' + ) + ) + + $resourceFiles = Get-ResourceFiles $ResourceName + + $resourceAST = ConvertTo-ParsedAST -ResourceName $resourceFiles.ModuleFile + + Write-Verbose -Message ( + $script:localizedData.VerboseParsingFunctions -f ($FunctionNames -join ', ') + ) + + $functionDefinitionAst = Get-DSCResourceFunctionsFromAST -Ast $resourceAST -FunctionNames $FunctionNames + + Write-Verbose -Message ( + $script:localizedData.VerboseParsingParameters -f ( + $foundFunctions.InputObject -join ', ' + ) + ) + + $helpDictionary = @{} + $functionDefinitionAst | ForEach-Object { + # https://stackoverflow.com/questions/45929043/get-all-functions-in-a-powershell-script + # Get the plain string comment block from the AST. + $functionName = $PSItem.Name + $commentBlock = $PSItem.GetHelpContent().GetCommentBlock() + + $scriptBlock = [scriptblock]::Create((' + function {0} {{ + {1} + param() + }}' -f $functionName, $commentBlock)) + + # Dot source the scriptblock in a different scope so we can + # get the help content but still not pollute the session. + & { + . $scriptBlock + + $helpObject = Get-Help $functionName + $helpDictionary[$functionName] = $helpObject + } + } + + return $helpDictionary +} + +function Get-DSCResourceFunctionsFromAST +{ + [CmdletBinding()] + param + ( + [System.Management.Automation.Language.Ast] + $Ast, + + [String[]] + $FunctionNames = @( + 'Get-TargetResource' + 'Test-TargetResource' + 'Set-TargetResource' + ) + ) + + $functionDefinitionAst = $resourceAST.FindAll( + { + param($Item) + return ( + $Item -is [System.Management.Automation.Language.FunctionDefinitionAst] -And + $Item.Name -in $FunctionNames + ) + }, + $true + ) + + # Check if we found all the functions, if not, show warning + if ($functionDefinitionAst.Count -lt 1) + { + throw ( + $script:localizedData.DidNotFindAnyFunctions -f ( + $FunctionNames -join ',' + ), $ResourceName + ) + } + else + { + $compareParameters = @{ + ReferenceObject = $FunctionNames + DifferenceObject = $functionDefinitionAst.Name + } + $missingFunctions = Compare-Object @compareParameters + $foundFunctions = Compare-Object @compareParameters -IncludeEqual -ExcludeDifferent + if ($missingFunctions) + { + Write-Warning -Message ( + $script:localizedData.DidNotFindFunction -f ( + ($missingFunctions.InputObject -join ', '), + ($foundFunctions.InputObject -join ', ') + ) + ) + } + } + + return $functionDefinitionAst +} + +<# +.SYNOPSIS + ConvertTo-ParsedAST + +.DESCRIPTION + This will check if the resource file is specified and if not, it will get + the file from the resource name + +.PARAMETER ResourceName + The resource module name or full path to the .psm1 file to process + +.OUTPUTS + This script will output an AST parsed file + +#> +Function ConvertTo-ParsedAST +{ + [CmdletBinding()] + param( + [Parameter(Mandatory=$true)] + [String] + $ResourceName + ) + + $getModuleParameters = @{ + Name = $ResourceName + ListAvailable = $True + } + + $parseErrors = $null + $astResourceParsed = $null + Write-Verbose -Message ( + $script:localizedData.GetModuleInfo -f $getModuleParameters.Name + ) + + if ($moduleInfo = Get-Module @getModuleParameters) + { + $astResourceParsed = [System.Management.Automation.Language.Parser]::ParseFile( + $getModuleParameters.Name, [ref] $null, [ref] $parseErrors + ) + } + else + { + throw ($script:localizedData.ErrorGetModuleInfo -f $ResourceName) + } + + if ($parseErrors.Count -ne 0) { + throw ( + $script:localizedData.ErrorParseAST -f $getModuleParameters.Name, $parseErrors + ) + } + + return $astResourceParsed +} + Export-ModuleMember -Function * diff --git a/DscResource.DocumentationHelper/Get-DSCResourceParameters.psm1 b/DscResource.DocumentationHelper/Get-DSCResourceParameters.psm1 deleted file mode 100644 index e35a34a4..00000000 --- a/DscResource.DocumentationHelper/Get-DSCResourceParameters.psm1 +++ /dev/null @@ -1,195 +0,0 @@ - -$projectRootPath = Split-Path -Path $PSScriptRoot -Parent -$testHelperPath = Join-Path -Path $projectRootPath -ChildPath 'TestHelper.psm1' -Import-Module -Name $testHelperPath -Force - -$script:localizedData = Get-LocalizedData -ModuleName 'Get-DSCResourceParameters' -ModuleRoot $PSScriptRoot - -<# -.SYNOPSIS - Get-DSCResourceParameters is used to get all the parameters that belong - to a specific DSC resource and a specific function in that resource. - -.DESCRIPTION - Uses AST to parse a DSC Resource module to get the parameters from it. - -.PARAMETER ResourceName - The resource module name or full path to the .psm1 file to process - -.PARAMETER FunctionNames - This gets the parameters for the functions inside the resource. - By default this would be: - 'Get-TargetResource', 'Test-TargetResource', 'Set-TargetResource' - -.OUTPUTS - This script will output a hashtable with the function and each parameter the - function has. @{} = [System.Management.Automation.Language.ParameterAst[]] - -.EXAMPLE - This example parses a psm1 file - - Get-DSCResourceParameters -ResourceName C:\DSC\MSFT_xAD\MSFT_xAD.psm1 - Get-DSCResourceParameters -ResourceName C:\DSC\MSFT_xAD\MSFT_xAD.psm1 ` - -FunctionName 'Get-TargetResource' - -#> -function Get-DSCResourceParameters -{ - [CmdletBinding()] - param( - [Parameter(Mandatory=$true)] - [String] - $ResourceName, - - [String[]] - $FunctionNames = @( - 'Get-TargetResource' - 'Test-TargetResource' - 'Set-TargetResource' - ) - ) - - Import-Module -Name ( - Join-Path -Path $PSScriptRoot -ChildPath 'DscResourceCommentHelper.psm1' - ) - $resourceFiles = Get-ResourceFiles $ResourceName - - $resourceAST = ConvertTo-ParsedAST -ResourceName $resourceFiles.ModuleFile - - Write-Verbose -Message ( - $script:localizedData.VerboseParsingFunctions -f ($FunctionNames -join ', ') - ) - $functionDefinitionAst = $resourceAST.FindAll( - { - param($Item) - return ( - $Item -is [System.Management.Automation.Language.FunctionDefinitionAst] -And - $Item.Name -in $FunctionNames - ) - }, - $true - ) - - # Check if we found all the functions, if not, show warning - if ($functionDefinitionAst.Count -lt 1) - { - throw ( - $script:localizedData.DidNotFindAnyFunctions -f ( - $FunctionNames -join ',' - ), $ResourceName - ) - } - else - { - $compareParameters = @{ - ReferenceObject = $FunctionNames - DifferenceObject = $functionDefinitionAst.Name - } - $missingFunctions = Compare-Object @compareParameters - $foundFunctions = Compare-Object @compareParameters -IncludeEqual -ExcludeDifferent - if ($missingFunctions) - { - Write-Warning -Message ( - $script:localizedData.DidNotFindFunction -f ( - ($missingFunctions.InputObject -join ', '), - ($foundFunctions.InputObject -join ', ') - ) - ) - } - } - - Write-Verbose -Message ( - $script:localizedData.VerboseParsingParameters -f ( - $foundFunctions.InputObject -join ', ' - ) - ) - $parameterDictionary = @{} - $functionDefinitionAst | ForEach-Object { - $functionName = $PSItem.Name - Write-Verbose -Message ( - $script:localizedData.VerboseFindParameters -f $functionName - ) - - $parameterDictionary[$functionName] = @() - - $functionParameters = $PSItem.Find( - { - param($Item) - return ( - $Item -is [System.Management.Automation.Language.ParamBlockAst] - ) - }, - $true - ) - - if ($functionParameters.Count -lt 1) - { - Write-Error -Message ( - $script:localizedData.NoParametersFound -f $functionName - ) - continue - } - - $parameterDictionary[$functionName] = $functionParameters.Parameters - } - - return $parameterDictionary -} - -<# -.SYNOPSIS - ConvertTo-ParsedAST - -.DESCRIPTION - This will check if the resource file is specified and if not, it will get - the file from the resource name - -.PARAMETER ResourceName - The resource module name or full path to the .psm1 file to process - -.OUTPUTS - This script will output an AST parsed file - -#> -Function ConvertTo-ParsedAST -{ - [CmdletBinding()] - param( - [Parameter(Mandatory=$true)] - [String] - $ResourceName - ) - - $getModuleParameters = @{ - Name = $ResourceName - ListAvailable = $True - } - - $parseErrors = $null - $astResourceParsed = $null - Write-Verbose -Message ( - $script:localizedData.GetModuleInfo -f $getModuleParameters.Name - ) - - if ($moduleInfo = Get-Module @getModuleParameters) - { - $astResourceParsed = [System.Management.Automation.Language.Parser]::ParseFile( - $getModuleParameters.Name, [ref] $null, [ref] $parseErrors - ) - } - else - { - throw ($script:localizedData.ErrorGetModuleInfo -f $ResourceName) - } - - if ($parseErrors.Count -ne 0) { - throw ( - $script:localizedData.ErrorParseAST -f $getModuleParameters.Name, $parseErrors - ) - } - - return $astResourceParsed -} - - -Export-ModuleMember -Function Get-DSCResourceParameters diff --git a/DscResource.DocumentationHelper/New-DscResourceCommentBasedHelp.psm1 b/DscResource.DocumentationHelper/New-DscResourceCommentBasedHelp.psm1 index dc110453..e131e317 100644 --- a/DscResource.DocumentationHelper/New-DscResourceCommentBasedHelp.psm1 +++ b/DscResource.DocumentationHelper/New-DscResourceCommentBasedHelp.psm1 @@ -63,21 +63,18 @@ Function New-DscResourceCommentBasedHelp Join-Path -Path $PSScriptRoot -ChildPath 'MofHelper.psm1' ) - Import-Module -Name ( - Join-Path -Path $PSScriptRoot -ChildPath 'Get-DSCResourceParameters.psm1' - ) - Import-Module -Name ( Join-Path -Path $PSScriptRoot -ChildPath 'DscResourceCommentHelper.psm1' ) $resourceFiles = Get-ResourceFiles $ResourceName - $moduleParameters = Get-DSCResourceParameters $resourceFiles.ModuleFile - $schemaParameters = Get-MofSchemaObject -FileName $resourceFiles.SchemaFile - + $moduleParameters = Get-DSCResourceParameters $resourceFiles.ModuleFile + $moduleHelpComments = Get-DSCResourceCommentBasedHelp $resourceFiles.ModuleFile + $schemaParameters = Get-MofSchemaObject -FileName $resourceFiles.SchemaFile + $outputStringsForEachFunction = @{} - $tab = [System.String]::new(' ',4) + $tab = [System.String]::new(' ', 4) foreach($function in $moduleParameters.Keys){ Write-Verbose -Message ( $script:localizedData.VerboseFunctionComments -f $function @@ -88,7 +85,7 @@ Function New-DscResourceCommentBasedHelp # Start Synopsis $null = $stringBuilder.AppendLine('<#') $null = $stringBuilder.AppendLine($tab + '.SYNOPSIS') - $null = $stringBuilder.AppendLine($tab + $tab + 'Synopsis here') + $null = $stringBuilder.AppendLine($tab + $tab + $moduleHelpComments[$function].Synopsis) $null = $stringBuilder.AppendLine('') # Add each parameter diff --git a/DscResource.DocumentationHelper/en-US/DscResourceCommentHelper.strings.psd1 b/DscResource.DocumentationHelper/en-US/DscResourceCommentHelper.strings.psd1 deleted file mode 100644 index 5165b7f9..00000000 --- a/DscResource.DocumentationHelper/en-US/DscResourceCommentHelper.strings.psd1 +++ /dev/null @@ -1,7 +0,0 @@ -# culture="en-US" -ConvertFrom-StringData @' - ResourceFileNotFound = The following file '{0}' does not exist, please verify that the file location is correct. - ResourceFilesNotFoundInDirectory = Could not find the resource files in the directory '{0}', please verify that the location is correct. - ResourceFilesFound = The resource files exist in the directory '{0}'. - ResourceInfoError = Could not retrieve the information for the resource '{0}', please verify that the resource exists. -'@ From 371cb6f2a2e71cf8028ad70d947999fb1cc67d99 Mon Sep 17 00:00:00 2001 From: Matthew Martinez Date: Wed, 24 Jul 2019 09:44:05 +0300 Subject: [PATCH 5/5] added comments for ast function --- .../DscResourceCommentHelper.psm1 | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 b/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 index a4e3eeab..7bd90caa 100644 --- a/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 +++ b/DscResource.DocumentationHelper/DscResourceCommentHelper.psm1 @@ -280,6 +280,26 @@ function Get-DSCResourceCommentBasedHelp return $helpDictionary } +<# +.SYNOPSIS + Get-DSCResourceFunctionsFromAST is used to get all the functions back within + a module file + +.DESCRIPTION + Uses AST to parse a DSC Resource module to get the required functions within + +.PARAMETER Ast + The parsed ast file to search within + +.PARAMETER FunctionNames + This gets the parameters for the functions inside the resource. + By default this would be: + 'Get-TargetResource', 'Test-TargetResource', 'Set-TargetResource' + +.OUTPUTS + [System.Management.Automation.Language.FunctionDefinitionAst] + + #> function Get-DSCResourceFunctionsFromAST { [CmdletBinding()]