Components/PS.Util.CommentHelp/Public/Convert-PSUtilCommentHelpToOutside.ps1
|
function Convert-PSUtilCommentHelpToOutside { [CmdletBinding()] param( [Parameter(Mandatory = $true)] [string]$FilePath, [Parameter(Mandatory = $true)] [string]$FunctionName ) # 1. Locate the targets $Target = Get-AstHelpPosition -FilePath $FilePath | Where-Object { $_.FunctionName -eq $FunctionName } if ($null -eq $Target -or $Target.HelpPosition -ne 'Inside') { Write-Warning "Function '$FunctionName' help is already Outside or does not exist." return } $RawContent = [System.IO.File]::ReadAllText($FilePath) $CommentText = $Target.CommentToken.Text # 2. Extract bounds $CommentStart = $Target.CommentToken.Extent.StartOffset $CommentLength = $Target.CommentToken.Extent.EndOffset - $CommentStart $FuncStart = $Target.FuncAst.Extent.StartOffset # 3. Surgical String Manipulation # Remove the comment from its original inside location $StrippedContent = $RawContent.Remove($CommentStart, $CommentLength) # Re-insert the comment cleanly directly above the function keyword header # Adjusting position slightly if stripping changed the index layout $FinalIndex = if ($CommentStart -lt $FuncStart) { $FuncStart - $CommentLength } else { $FuncStart } $FinalContent = $StrippedContent.Insert($FinalIndex, "$CommentText`n") [System.IO.File]::WriteAllText($FilePath, $FinalContent) Write-Verbose "Moved comment-based help for '$FunctionName' to the OUTSIDE." } |