Update help docs for Commands submodule

This change fixes some mistakes in the help documents for the Commands
module and adds additional examples.

Author: SeeminglyScience

module/docs/ConvertFrom-ScriptExtent.md

@@ -26,18 +26,20 @@ ConvertFrom-ScriptExtent -Extent <IScriptExtent[]> [-BufferPosition] [-Start] [-
 
 ## DESCRIPTION
 
-Translates IScriptExtent object properties into constructors for some common PowerShell EditorServices types.
+The ConvertFrom-ScriptExtent function converts ScriptExtent objects to types used in methods found in the $psEditor API.
 
 ## EXAMPLES
 
 ### -------------------------- EXAMPLE 1 --------------------------
 
 ```powershell
-$sb = { Get-ChildItem 'Documents' }
-$sb.Ast | Find-Ast { $_ -eq 'Documents' } | ConvertFrom-ScriptExtent -BufferRange
+$range = Find-Ast -First { [System.Management.Automation.Language.CommandAst] } |
+    ConvertFrom-ScriptExtent -BufferRange
+
+$psEditor.GetEditorContext().SetSelection($range)
 ```
 
-Gets the buffer range of the string expression "Documents".
+Convert the extent of the first CommandAst to a BufferRange and use that to select it with the $psEditor API.
 
 ## PARAMETERS
 
@@ -129,18 +131,21 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ### System.Management.Automation.Language.IScriptExtent
 
-You can pipe IScriptExtent objects to be converted.
+You can pass ScriptExtent objects to this function.  You can also pass objects with a property named "Extent" such as ASTs from Find-Ast or tokens from Get-Token.
 
 ## OUTPUTS
 
 ### Microsoft.PowerShell.EditorServices.BufferRange
 
 ### Microsoft.PowerShell.EditorServices.BufferPosition
 
-This function will return an extent converted to one of the above types depending on switch
-choices.
+This function will return the converted object of one of the above types depending on parameter switch choices.
 
 ## NOTES
 
 ## RELATED LINKS
 
+[ConvertTo-ScriptExtent](ConvertTo-ScriptExtent.md)
+[Test-ScriptExtent](Test-ScriptExtent.md)
+[Set-ScriptExtent](Set-ScriptExtent.md)
+[Join-ScriptExtent](Join-ScriptExtent.md)

module/docs/ConvertTo-ScriptExtent.md

@@ -12,10 +12,10 @@ Converts position and range objects from PowerShellEditorServices to ScriptExten
 
 ## SYNTAX
 
-### ByObject
+### ByExtent
 
 ```powershell
-ConvertTo-ScriptExtent [-InputObject <IScriptExtent>] [<CommonParameters>]
+ConvertTo-ScriptExtent [-Extent <IScriptExtent>] [<CommonParameters>]
 ```
 
 ### ByPosition
@@ -41,7 +41,7 @@ ConvertTo-ScriptExtent [-FilePath <String>] [-StartBuffer <BufferPosition>] [-En
 
 ## DESCRIPTION
 
-Converts position and range objects from PowerShellEditorServices to ScriptExtent objects.
+The ConvertTo-ScriptExtent function can be used to convert any object with position related properties to a ScriptExtent object.  You can also specify the parameters directly to manually create ScriptExtent objects.
 
 ## EXAMPLES
 
@@ -51,17 +51,25 @@ Converts position and range objects from PowerShellEditorServices to ScriptExten
 $psEditor.GetEditorContext().SelectedRange | ConvertTo-ScriptExtent
 ```
 
-Returns a InternalScriptExtent object of the currently selected range.
+Returns a ScriptExtent object of the currently selected range.
+
+### -------------------------- EXAMPLE 2 --------------------------
+
+```powershell
+ConvertTo-ScriptExtent -StartOffset 10 -EndOffset 100
+```
+
+Returns a ScriptExtent object from a start and end offset.
 
 ## PARAMETERS
 
-### -InputObject
+### -Extent
 
-This is here so we can pass script extent objects through without any processing.
+Specifies a ScriptExtent object to use as a base to create a new editor context aware ScriptExtent object.
 
 ```yaml
 Type: IScriptExtent
-Parameter Sets: ByObject
+Parameter Sets: ByExtent
 Aliases:
 
 Required: False
@@ -223,29 +231,23 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ### System.Object
 
-You can pass any object with any of the following properties.
+You can pass any object with properties that have position related names.  Below is a list of all the property names that can be bound as parameters through the pipeline.
 
-StartLineNumber, StartLine, Line
-EndLineNumber, EndLine
-StartColumnNumber, StartColumn, Column
-EndColumnNumber, EndColumn
-StartOffsetNumber, StartOffset, Offset
-EndOffsetNumber, EndOffset
-StartBuffer, Start
-EndBuffer, End
+StartLineNumber, StartLine, Line, EndLineNumber, EndLine, StartColumnNumber, StartColumn, Column, EndColumnNumber, EndColumn, StartOffsetNumber, StartOffset, Offset, EndOffsetNumber, EndOffset, StartBuffer, Start, EndBuffer, End
 
-Objects of type IScriptExtent will be passed through with no processing.
+You can also pass IScriptExtent objects to be converted to context aware versions.
 
 ## OUTPUTS
 
-### System.Management.Automation.Language.IScriptExtent
-
-### System.Management.Automation.Language.InternalScriptExtent
+### Microsoft.PowerShell.EditorServices.FullScriptExtent
 
-This function will return any IScriptExtent object passed without processing. Objects created
-by this function will be of type InternalScriptExtent.
+The converted ScriptExtent object will be returned to the pipeline.
 
 ## NOTES
 
 ## RELATED LINKS
 
+[ConvertFrom-ScriptExtent](ConvertFrom-ScriptExtent.md)
+[Test-ScriptExtent](Test-ScriptExtent.md)
+[Set-ScriptExtent](Set-ScriptExtent.md)
+[Join-ScriptExtent](Join-ScriptExtent.md)

module/docs/Find-Ast.md

@@ -8,7 +8,7 @@ schema: 2.0.0
 
 ## SYNOPSIS
 
-Search for a ast within an ast.
+Find a specific element in an abstract syntax tree (AST).
 
 ## SYNTAX
 
@@ -27,7 +27,9 @@ Find-Ast [-AtCursor] [<CommonParameters>]
 
 ## DESCRIPTION
 
-The Find-Ast function can be used to easily find a specific ast from a starting ast. By default children asts will be searched, but ancestor asts can also be searched by specifying the "Ancestor" switch parameter.
+The Find-Ast function can be used to easily find a specific AST within a script file. All ASTs following the inital starting ast will be searched, including those that are not part of the same tree.
+
+The behavior of the search (such as direction and criteria) can be changed with parameters.
 
 Additionally, you can find the Ast closest to the cursor with the "AtCursor" switch parameter.
 
@@ -76,16 +78,50 @@ Returns all variable expressions used in a dot source expression.
 ### -------------------------- EXAMPLE 6 --------------------------
 
 ```powershell
-Find-Ast { 'PowerShellVersion' -eq $_ } | Find-Ast -First | Set-ScriptExtent -Text "'4.0'"
+Find-Ast { 'PowerShellVersion' -eq $_ } |
+    Find-Ast -First |
+    Set-ScriptExtent -Text '4.0' -AsString
+```
+
+This example sets the required PowerShell version in a module manifest to 4.0.
+
+First it finds the AST of the PowerShellVersion manifest field, then finds the first AST directly after it and changes the text to '4.0'. This will not work as is if the field is commented.
+
+### -------------------------- EXAMPLE 7 --------------------------
+
+```powershell
+Find-Ast { $_.ArgumentName -eq 'ParameterSetName' -and $_.Argument.Value -eq 'ByPosition' } |
+    Find-Ast -First -Ancestor { $_ -is [System.Management.Automation.Language.ParameterAst] } |
+    ForEach-Object { $_.Name.VariablePath.UserPath }
+```
+
+This example gets a list of all parameters that belong to the parameter set 'ByPosition'. First it uses the ArgumentName and Argument properties of NamedAttributeArgumentAst to find the ASTs of arguments to the Parameter attribute that declare the the parameter set 'ByPosition'.  It then finds the closest parent ParameterAst and retrieves the name from it.
+
+### -------------------------- EXAMPLE 8 --------------------------
+
+```powershell
+$companyName = Find-Ast {
+    $_.Value -eq 'CompanyName' -or
+    (Find-Ast -Ast $_ -First -Before).Value -eq 'CompanyName'
+}
+
+$previousField = $companyName[0] | Find-Ast -First -Before { $_.StringConstantType -eq 'BareWord' }
+
+$companyNameComments = $companyName.Extent, $previousField.Extent |
+    Join-ScriptExtent |
+    Get-Token |
+    Where-Object Kind -eq 'Comment'
+
+$fullManifestElement = $companyNameComments.Extent, $companyName.Extent | Join-ScriptExtent
 ```
 
-First finds the ast of the PowerShellVersion manifest tag, then finds the first ast after it and changes the text to '4.0'. This will not work as is if the field is commented.
+This example shows off ways you can combine the position functions together to get very specific portions of a script file.  The result of this example is a ScriptExtent that includes a manifest field, value, and all comments above it.
 
 ## PARAMETERS
 
 ### -FilterScript
 
-Specifies a ScriptBlock that returns $true if an ast should be returned. Uses $PSItem and $_ like Where-Object. If not specified all asts will be returned.
+Specifies a ScriptBlock that returns $true if an AST should be returned. Uses $PSItem and $_ like Where-Object. If not specified all ASTs will be returned.
 
 ```yaml
 Type: ScriptBlock
@@ -101,7 +137,7 @@ Accept wildcard characters: False
 
 ### -Ast
 
-Specifies the starting ast. The default is the ast of the current file in PowerShell Editor Services.
+Specifies the starting AST. The default is the AST of the current file in PowerShell Editor Services.
 
 ```yaml
 Type: Ast
@@ -133,7 +169,7 @@ Accept wildcard characters: False
 
 ### -Family
 
-If specified only children of the starting ast will be searched. If specified with the "Before" parameter then only ancestors will be searched.
+If specified only children of the starting AST will be searched. If specified with the "Before" parameter then only ancestors will be searched.
 
 ```yaml
 Type: SwitchParameter
@@ -149,7 +185,7 @@ Accept wildcard characters: False
 
 ### -First
 
-If specified will return only the first result. This will be the closest ast that matches.
+If specified will return only the first result. This will be the closest AST that matches.
 
 ```yaml
 Type: SwitchParameter
@@ -165,7 +201,7 @@ Accept wildcard characters: False
 
 ### -Last
 
-If specified will return only the last result. This will be the furthest ast that matches.
+If specified will return only the last result. This will be the furthest AST that matches.
 
 ```yaml
 Type: SwitchParameter
@@ -181,7 +217,7 @@ Accept wildcard characters: False
 
 ### -Ancestor
 
-If specified will only search ancestors of the starting ast.  This is a convenience parameter that acts the same as the "Family" and "Before" parameters when used together.
+If specified will only search ancestors of the starting AST.  This is a convenience parameter that acts the same as the "Family" and "Before" parameters when used together.
 
 ```yaml
 Type: SwitchParameter
@@ -197,7 +233,7 @@ Accept wildcard characters: False
 
 ### -IncludeStartingAst
 
-If specified the starting ast will be included if matched.
+If specified the starting AST will be included if matched.
 
 ```yaml
 Type: SwitchParameter
@@ -213,7 +249,7 @@ Accept wildcard characters: False
 
 ### -AtCursor
 
-If specified, this function will return the smallest ast that the cursor is within. Requires PowerShell Editor Services.
+If specified, this function will return the smallest AST that the cursor is within.
 
 ```yaml
 Type: SwitchParameter
@@ -235,15 +271,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ### System.Management.Automation.Language.Ast
 
-You can pass asts to search to this function.
+You can pass ASTs to search to this function.
 
 ## OUTPUTS
 
 ### System.Management.Automation.Language.Ast
 
-Asts that match the criteria will be returned to the pipeline.
+ASTs that match the criteria will be returned to the pipeline.
 
 ## NOTES
 
 ## RELATED LINKS
 
+[Get-Token](Get-Token.md)
+[Set-ScriptExtent](Set-ScriptExtent.md)
+[ConvertTo-ScriptExtent](ConvertTo-ScriptExtent.md)

module/docs/Import-EditorCommand.md

@@ -8,20 +8,20 @@ schema: 2.0.0
 
 ## SYNOPSIS
 
-Imports commands with the PSEditorCommand attribute into PowerShell Editor Services.
+Imports commands with the EditorCommand attribute into PowerShell Editor Services.
 
 ## SYNTAX
 
 ### ByModule
 
 ```powershell
-Import-EditorCommand [-Module] <PSModuleInfo[]> [-Force] [-PassThru] [<CommonParameters>]
+Import-EditorCommand [-Module] <string[]> [-Force] [-PassThru] [<CommonParameters>]
 ```
 
 ### ByCommand
 
 ```powershell
-Import-EditorCommand [-Command] <CommandInfo[]> [-Force] [-PassThru] [<CommonParameters>]
+Import-EditorCommand [-Command] <string[]> [-Force] [-PassThru] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -30,6 +30,8 @@ The Import-EditorCommand function will search the specified module for functions
 
 Alternatively, you can specify command info objects (like those from the Get-Command cmdlet) to be processed directly.
 
+To tag a command as an editor command, attach the attribute 'Microsoft.PowerShell.EditorServices.Extensions.EditorCommandAttribute' to the function like you would with 'CmdletBindingAttribute'.  The attribute accepts the named parameters 'Name', 'DisplayName', and 'SuppressOutput'.
+
 ## EXAMPLES
 
 ### -------------------------- EXAMPLE 1 --------------------------
@@ -48,6 +50,23 @@ Get-Command *Editor* | Import-EditorCommand -PassThru
 
 Registers all editor commands that contain "Editor" in the name and return all successful imports.
 
+### -------------------------- EXAMPLE 3 --------------------------
+
+```powershell
+function Invoke-MyEditorCommand {
+    [CmdletBinding()]
+    [Microsoft.PowerShell.EditorServices.Extensions.EditorCommand(DisplayName='My Command', SuppressOutput)]
+    param()
+    end {
+        ConvertTo-ScriptExtent -Offset 0 | Set-ScriptExtent -Text 'My Command!'
+    }
+}
+
+Get-Command Invoke-MyEditorCommand | Import-EditorCommand
+```
+
+This example declares the function Invoke-MyEditorCommand with the EditorCommand attribute and then imports it as an editor command.
+
 ## PARAMETERS
 
 ### -Module
@@ -68,7 +87,7 @@ Accept wildcard characters: False
 
 ### -Command
 
-Specifies the functions to register as editor commands. If the function does not have the PSEditorCommand attribute it will be ignored.
+Specifies the functions to register as editor commands. If the function does not have the EditorCommand attribute it will be ignored.
 
 ```yaml
 Type: string[]
@@ -135,3 +154,5 @@ will be returned.  This function does not output to the pipeline otherwise.
 
 ## RELATED LINKS
 
+[Register-EditorCommand](Register-EditorCommand.md)
+[Unregister-EditorCommand](Unregister-EditorCommand.md)