Add CrescendoBuilt to docs (#93)

MicrosoftDocs · Aug 18, 2022 · 27ecb4a · 27ecb4a
1 parent e74c14a
commit 27ecb4a
Show file tree

Hide file tree

Showing 2 changed files with 51 additions and 41 deletions.
diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/about_Crescendo.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/about_Crescendo.md
@@ -1,7 +1,7 @@
 ---
 description: Describes the purpose of the Crescendo module.
 Locale: en-US
-ms.date: 01/21/2022
+ms.date: 08/18/2022
 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.crescendo/about/about_Microsoft.PowerShell.Crescendo?view=ps-modules.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Microsoft.PowerShell.Crescendo
@@ -10,26 +10,26 @@ title: about_Microsoft.PowerShell.Crescendo
 
 ## about_Microsoft.PowerShell.Crescendo
 
-## SHORT DESCRIPTION
+## Short description
 
 The PowerShell Crescendo module provides a novel way to create proxy functions
 for native commands via `JSON` configuration files.
 
-## LONG DESCRIPTION
+## Long description
 
 PowerShell is capable of invoking native applications like any shell. However,
 it would improve the experience if the native command could participate in the
 PowerShell pipeline and take advantage of the parameter behaviors that are part
 of PowerShell.
 
-The PowerShell Crescendo module provides a way to more easily take advantage of
-the PowerShell pipeline by invoking the native executable, facilitating
-parameter handling, and converting text output into objects.
+The PowerShell Crescendo module provides a way to take advantage of the
+PowerShell pipeline by invoking the native executable, facilitating parameter
+handling, and converting text output into objects.
 
 ## JSON Configuration
 
 The PowerShell Crescendo module provides a way to create a small bit of JSON
-that is used to create a function that calls the native command.
+that's used to create a function that calls the native command.
 
 An annotated schema is provided as part of the module that can improve the
 authoring process.
@@ -41,9 +41,9 @@ commands in the same way you do with cmdlets.
 
 ## Output Handling
 
-It is also possible to provide a script block that can be used to convert the
-output from the native command into objects. If the native command emits `json`
-or `xml` it is as simple as:
+It's also possible to create a script block that can be used to convert the
+output from the native command into objects. If the native command emits JSON
+or XML it can be as simple as:
 
 ```json
     "OutputHandler": [
@@ -54,12 +54,12 @@ or `xml` it is as simple as:
 
 However, script blocks of arbitrary complexity may also be used.
 
-## EXAMPLES
+## Examples
 
-A number of samples are provided as part of the module, you can see these in
-the Samples directory in the module base directory.
+Several samples are provided as part of the module. You can find these in the
+`Samples` directory of the module base directory.
 
-A very simple example is as follows to wrap the unix `/bin/ls` command:
+The following JSON is a minimal example that wraps the unix `/bin/ls` command:
 
 ```json
 {
@@ -68,32 +68,42 @@ A very simple example is as follows to wrap the unix `/bin/ls` command:
     "Noun":"FileList",
     "OriginalName": "/bin/ls",
     "Parameters": [
-        {"Name": "Path","OriginalName": "", "OriginalPosition": 1, "Position": 0, "DefaultValue": "." },
-        {"Name": "Detail","OriginalName": "-l","ParameterType": "switch"}
+        {
+            "Name": "Path",
+            "OriginalName": "",
+            "OriginalPosition": 1,
+            "Position": 0,
+            "DefaultValue": "."
+        },
+        {
+            "Name": "Detail",
+            "OriginalName": "-l",
+            "ParameterType": "switch"
+        }
     ]
 }
 ```
 
 The name of the proxy function is `Get-FileList` and has two parameters:
 
-- Path
+- **Path**
   - Which is Position 0, and has a default value of "."
-- Detail
+- **Detail**
   - Which is a switch parameter and adds `-l` to the native command parameters
 
 A couple of things to note about the Path parameter
 
 - The `OriginalPosition` is set to 1 and the `OriginalName` is set to an empty
-  string. This is because some native commands have a parameter which is _not_
-  named and must be the last parameter when executed. All parameters will be
-  ordered by the value of `OriginalPosition` (the default is 0) and when the
-  native command is called, those parameters (and their values) will be put in
-  that order.
+  string. This is because some native commands have a parameter that is _not_
+  named and must be the last parameter when executed. All parameters get
+  ordered by the value of `OriginalPosition` (the default is 0). When the
+  native command is called, those parameters (and their values) are put in that
+  order.
 
 In this example, there is no output handler defined, so the text output of the
-command will be returned to the pipeline.
+command is returned to the pipeline.
 
-A more complicated example which wraps the linux `apt` command follows:
+The following is a more complicated example that wraps the linux `apt` command:
 
 ```json
 {
@@ -117,7 +127,7 @@ A more complicated example which wraps the linux `apt` command follows:
 
 In this case, the output handler converts the text output to a `pscustomobject`
 to enable using other PowerShell cmdlets. When run, this provides an object
-which encapsulates the `apt` output
+that encapsulates the `apt` output
 
 ```powershell
 PS> get-installedpackage | ?{ $_.name -match "libc"}
@@ -138,16 +148,10 @@ Count Name  Group
    82 amd64 {@{Name=apt; Version=2.0.2ubuntu0.1; Architecture=amd64; State=System.String[]}, @{Name=base-files…
 ```
 
-## TROUBLESHOOTING NOTE
-
-The PowerShell Crescendo module is still very early in the development process,
-so we expect changes to be made.
-
-One issue is that the output handler is currently a string, so constructing the
-script block may be complex; semi-colons will be required to separate
-statements. This may be addressed in a later version.
+## See also
 
-## SEE ALSO
+The PowerShell Crescendo module is still in the development process, so we
+expect changes to be made.
 
 The GitHub repository may be found at:
 [https://github.com/PowerShell/Crescendo](https://github.com/PowerShell/Crescendo).
@@ -158,6 +162,6 @@ command wrapping can be found here:
 - [Part 1](https://devblogs.microsoft.com/powershell/native-commands-in-powershell-a-new-approach/)
 - [Part 2](https://devblogs.microsoft.com/powershell/native-commands-in-powershell-a-new-approach-part-2))
 
-## KEYWORDS
+## Keywords
 
 Native Command
diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-CrescendoModule.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-CrescendoModule.md
@@ -43,7 +43,7 @@ Export-CrescendoModule netsh netsh*.json -force
 
 ### -ConfigurationFile
 
-This is a list of JSON files which represent the proxies for the module
+This is a list of JSON files that represent the proxies for the module.
 
 ```yaml
 Type: System.String[]
@@ -59,9 +59,8 @@ Accept wildcard characters: True
 
 ### -Force
 
-By default, if `Export-CrescendoModule` finds an already created module, it will not overwrite the
-existing file. Use the **Force** parameter to overwrite the existing file, or remove it prior to
-running `Export-CrescendoModule`.
+By default, if `Export-CrescendoModule` does not overwrite an existing module. Use the **Force**
+parameter to overwrite the existing file, or remove it before running `Export-CrescendoModule`.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -109,7 +108,7 @@ Accept wildcard characters: False
 
 ### -WhatIf
 
-Shows what would happen if the cmdlet runs. The cmdlet is not run.
+Shows what would happen if the cmdlet runs. The cmdlet isn't run.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -144,6 +143,13 @@ individual function. Finally, all proxies are used to create an `Export-ModuleMe
 invocation, so when the resultant module is imported, the module has all the command proxies
 available.
 
+`Export-CrescendoModule` adds the **CrescendoBuilt** tag to the module manifest. You can use this
+tag to find modules in the PowerShell Gallery that were created using Crescendo. For more
+information, see:
+
+- [Gallery Search Syntax](/powershell/scripting/gallery/how-to/finding-packages/search-syntax)
+- [Find-Module](/powershell/module/powershellget/find-module)
+
 ## RELATED LINKS
 
 [Import-CommandConfiguration](Import-CommandConfiguration.md)