More doc cleanup

VertigoRay · Jan 24, 2023 · 79b68e6 · 79b68e6
1 parent b4ec7f6
commit 79b68e6
Show file tree

Hide file tree

Showing 6 changed files with 53 additions and 19 deletions.
diff --git a/.build/buildPsake.ps1 b/.build/buildPsake.ps1
@@ -338,10 +338,38 @@ task Docs {
                 # Don't add "SYNOPSIS" header.
                 # Ref: https://apastyle.apa.org/style-grammar-guidelines/paper-format/headings#:~:text=Headings%20in%20the%20introduction
                 Write-Host ('[PSAKE Docs] Removing: {0}' -f $line) -ForegroundColor 'DarkMagenta'
-            } elseif ($line -match '\\([[\]`])') {
-                # https://regex101.com/r/a7QMx3
+            } elseif (($line.Trim() -eq '## OUTPUTS') -or $inOutputs) {
+                if ($inOutputs) {
+                    if ($line.Trim().StartsWith('## ')) {
+                        $inOutputs = $false
+                        Write-Output $line
+                    } elseif ($line.Trim().StartsWith('### ')) {
+                        Write-Host ('[PSAKE Docs] Editing:{1}{0}' -f $line, "`t") -ForegroundColor 'DarkMagenta'
+                        $newline = '`{0}`' -f $line.Trim().Substring(4)
+                        Write-Host ('{1}{1}>>{1}{0}' -f $newline, "`t") -ForegroundColor 'DarkMagenta'
+                        Write-Output $newline
+                    }
+                } else {
+                    $inOutputs = $true
+                    Write-Output $line
+                }
+            } elseif (($line.Trim() -eq '### EXAMPLE') -or $inExample) {
+                if ($inExample) {
+                    if ($line.Trim().StartsWith('```')) {
+                        Write-Host ('[PSAKE Docs] Editing:{1}{0}' -f $line, "`t") -ForegroundColor 'DarkMagenta'
+                        $newline = '```powershell'
+                        Write-Host ('{1}{1}>>{1}{0}' -f $newline, "`t") -ForegroundColor 'DarkMagenta'
+                        Write-Output $newline
+                        $inExample = $false
+                    }
+                } else {
+                    $inExample = $true
+                    Write-Output $line
+                }
+            } elseif ($line -match '\\([[\]`\>])') {
+                # https://regex101.com/r/pBXaJE/3
                 Write-Host ('[PSAKE Docs] Editing:{1}{0}' -f $line, "`t") -ForegroundColor 'DarkMagenta'
-                $newline = $line -replace '\\([[\]`])', '$1'
+                $newline = $line -replace '\\([[\]`\>)', '$1'
                 Write-Host ('{1}{1}>>{1}{0}' -f $newline, "`t") -ForegroundColor 'DarkMagenta'
                 Write-Output $newline
             } else {

diff --git a/PSRedstone/Public/Assert-RedstoneIsMutexAvailable.ps1 b/PSRedstone/Public/Assert-RedstoneIsMutexAvailable.ps1
@@ -17,10 +17,11 @@ Assert-RedstoneIsMutexAvailable -MutexName 'Global\_MSIExecute' -MutexWaitTimeIn
 .EXAMPLE
 Assert-RedstoneIsMutexAvailable -MutexName 'Global\_MSIExecute' -MutexWaitTimeInMilliseconds (New-TimeSpan -Seconds 60).TotalMilliseconds
 .NOTES
-Copyright (C) 2015 - PowerShell App Deployment Toolkit Team
-Copyright (C) 2023 - Raymond Piller (VertigoRay)
-
 - [_MSIExecute Mutex](https://learn.microsoft.com/en-us/windows/win32/msi/-msiexecute-mutex)
+
+> Copyright Ⓒ 2015 - PowerShell App Deployment Toolkit Team
+>
+> Copyright Ⓒ 2023 - Raymond Piller (VertigoRay)
 .LINK
 https://github.com/VertigoRay/PSRedstone/wiki/Functions/#assert-redstoneismutexavailable
 #>

diff --git a/PSRedstone/Public/Assert-RedstoneIsNonInteractiveShell.ps1 b/PSRedstone/Public/Assert-RedstoneIsNonInteractiveShell.ps1
@@ -4,8 +4,8 @@ Is the current process running in a non-interactive shell?
 .DESCRIPTION
 There are two ways to determine if the current process is in a non-interactive shell:
 
-- See if the user environment is makred as interactive.
-- See if powershell was launced with the -NonInteractive
+- See if the user environment is marked as interactive.
+- See if PowerShell was launched with the -NonInteractive
 .EXAMPLE
 Assert-RedstoneIsNonInteractiveShell
 If you're typing this into PowerShell, you should see `$false`.

diff --git a/PSRedstone/Public/Get-RedstoneMsiExitCodeMessage.ps1 b/PSRedstone/Public/Get-RedstoneMsiExitCodeMessage.ps1
@@ -13,8 +13,9 @@ Get-RedstoneMsiExitCodeMessage -MsiExitCode 1618
 This is an internal script function and should typically not be called directly.
 - https://learn.microsoft.com/en-us/previous-versions//aa368542(v=vs.85)
 
-Copyright (C) 2015 - PowerShell App Deployment Toolkit Team
-Copyright (C) 2023 - Raymond Piller (VertigoRay)
+> Copyright Ⓒ 2015 - PowerShell App Deployment Toolkit Team
+>
+> Copyright Ⓒ 2023 - Raymond Piller (VertigoRay)
 .LINK
 https://github.com/VertigoRay/PSRedstone/wiki/Functions#get-redstonemsiexitcodemessage
 #>

diff --git a/PSRedstone/Public/Get-RedstoneMsiTableProperty.ps1 b/PSRedstone/Public/Get-RedstoneMsiTableProperty.ps1
@@ -33,8 +33,9 @@ Get-RedstoneMsiTableProperty -Path 'C:\Package\AppDeploy.msi' -GetSummaryInforma
 .NOTES
 This is an internal script function and should typically not be called directly.
 
-Copyright (C) 2015 - PowerShell App Deployment Toolkit Team
-Copyright (C) 2023 - Raymond Piller (VertigoRay)
+> Copyright Ⓒ 2015 - PowerShell App Deployment Toolkit Team
+>
+> Copyright Ⓒ 2023 - Raymond Piller (VertigoRay)
 .LINK
 https://github.com/VertigoRay/PSRedstone/wiki/Functions#get-redstonemsitableproperty
 #>

diff --git a/PSRedstone/Public/Invoke-RedstoneCmd.ps1 b/PSRedstone/Public/Invoke-RedstoneCmd.ps1
@@ -2,9 +2,17 @@
 .SYNOPSIS
 Runs the given command in ComSpec (aka: Command Prompt).
 .DESCRIPTION
-This just runs a command in ComSpec by passing it to `Invoke-RedstoneRun`.
+This just runs a command in ComSpec by passing it to `Invoke-RedstoneRun`. If you don't *need* ComSpec to run the command, it's normally best to just use `Invoke-RedstoneRun`.
 
-If you don't *need* ComSpec to run the command, it's normally best to just use `Invoke-RedstoneRun`.
+Returns the same object as `Invoke-RedstoneRun`
+
+```
+@{
+    'Process' = $proc; # The result from Start-Process; as returned from `Invoke-RedstoneRun`.
+    'StdOut'  = $stdout;
+    'StdErr'  = $stderr;
+}
+```
 .PARAMETER Cmd
 Under normal usage, the string passed in here just gets appended to `cmd.exe /c `.
 .PARAMETER KeepOpen
@@ -24,11 +32,6 @@ Applies /A:  Causes the output of internal commands to a pipe or file to be ANSI
 Applies /U:  Causes the output of internal commands to a pipe or file to be Unicode
 .OUTPUTS
 [Hashtable] As returned from `Invoke-RedstoneRun`.
-@{
-    'Process' = $proc; # The result from Start-Process; as returned from `Invoke-RedstoneRun`.
-    'StdOut'  = $stdout;
-    'StdErr'  = $stderr;
-}
 .EXAMPLE
 Invoke-RedstoneCmd "MKLINK /D Temp C:\Temp"
 .LINK