Fixes #8351 - Document module metadata for experimental features

reference/7.0/Microsoft.PowerShell.Core/About/about_Experimental_Features.md

@@ -1,7 +1,7 @@
 ---
 description: The Experimental Features support in PowerShell provides a mechanism for experimental features to coexist with existing stable features in PowerShell or PowerShell modules.
 Locale: en-US
-ms.date: 03/13/2020
+ms.date: 11/15/2021
 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_experimental_features?view=powershell-7&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Experimental Features
@@ -48,7 +48,7 @@ specified and the only valid values are:
 - `Show` means to show this experimental feature if the feature is enabled
 - `Hide` means to hide this experimental feature if the feature is enabled
 
-### Declaring Experimental Features in Modules Written in C\#
+## Declaring Experimental Features in Modules Written in C\#
 
 Module authors who want to use the Experimental Feature flags can declare a
 cmdlet as experimental by using the `Experimental` attribute.
@@ -59,7 +59,7 @@ cmdlet as experimental by using the `Experimental` attribute.
 public class InvokeWebRequestCommandV2 : WebCmdletBaseV2 { ... }
 ```
 
-### Declaring Experimental Features in Modules written in PowerShell
+## Declaring Experimental Features in Modules written in PowerShell
 
 Module written in PowerShell can also use the `Experimental` attribute to
 declare experimental cmdlets:
@@ -73,7 +73,32 @@ function Enable-SSHRemoting {
 }
 ```
 
-### Mutually Exclusive Experimental Features
+Metadata about an experimental feature is kept in the module manifest. Use the
+`PrivateData.PSData.ExperimentalFeatures` property of a module manifest to
+expose the experimental features from the module. The `ExperimentalFeatures`
+property is an array of hashtables containing the name and description of the
+feature.
+
+For example:
+
+```powershell
+PrivateData = @{
+  PSData = @{
+    ExperimentalFeatures = @(
+      @{
+          Name = "PSWebCmdletV2"
+          Description = "Rewrite the web cmdlets for better performance"
+      },
+      @{
+          Name = "PSRestCmdletV2"
+          Description = "Rewrite the REST API cmdlets for better performance"
+      }
+    )
+  }
+}
+```
+
+## Mutually Exclusive Experimental Features
 
 There are cases where an experimental feature cannot co-exist side-by-side with
 an existing feature or another experimental feature.
@@ -108,7 +133,7 @@ When the `MyWebCmdlets.PSWebCmdletV2` experimental feature is enabled, the exist
 This allows users to try out the new cmdlet and provide feedback then revert
 to the non-experimental version when needed.
 
-### Experimental Parameters in Cmdlets
+## Experimental Parameters in Cmdlets
 
 The `Experimental` attribute can also be applied to individual parameters. This
 allows you to create an experimental set of parameters for an existing cmdlet

reference/7.1/Microsoft.PowerShell.Core/About/about_Experimental_Features.md

@@ -1,7 +1,7 @@
 ---
 description: The Experimental Features support in PowerShell provides a mechanism for experimental features to coexist with existing stable features in PowerShell or PowerShell modules.
 Locale: en-US
-ms.date: 03/13/2020
+ms.date: 11/15/2021
 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_experimental_features?view=powershell-7.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Experimental Features
@@ -48,7 +48,7 @@ specified and the only valid values are:
 - `Show` means to show this experimental feature if the feature is enabled
 - `Hide` means to hide this experimental feature if the feature is enabled
 
-### Declaring Experimental Features in Modules Written in C\#
+## Declaring Experimental Features in Modules Written in C\#
 
 Module authors who want to use the Experimental Feature flags can declare a
 cmdlet as experimental by using the `Experimental` attribute.
@@ -59,7 +59,7 @@ cmdlet as experimental by using the `Experimental` attribute.
 public class InvokeWebRequestCommandV2 : WebCmdletBaseV2 { ... }
 ```
 
-### Declaring Experimental Features in Modules written in PowerShell
+## Declaring Experimental Features in Modules written in PowerShell
 
 Module written in PowerShell can also use the `Experimental` attribute to
 declare experimental cmdlets:
@@ -73,7 +73,32 @@ function Enable-SSHRemoting {
 }
 ```
 
-### Mutually Exclusive Experimental Features
+Metadata about an experimental feature is kept in the module manifest. Use the
+`PrivateData.PSData.ExperimentalFeatures` property of a module manifest to
+expose the experimental features from the module. The `ExperimentalFeatures`
+property is an array of hashtables containing the name and description of the
+feature.
+
+For example:
+
+```powershell
+PrivateData = @{
+  PSData = @{
+    ExperimentalFeatures = @(
+      @{
+          Name = "PSWebCmdletV2"
+          Description = "Rewrite the web cmdlets for better performance"
+      },
+      @{
+          Name = "PSRestCmdletV2"
+          Description = "Rewrite the REST API cmdlets for better performance"
+      }
+    )
+  }
+}
+```
+
+## Mutually Exclusive Experimental Features
 
 There are cases where an experimental feature cannot co-exist side-by-side with
 an existing feature or another experimental feature.
@@ -108,7 +133,7 @@ When the `MyWebCmdlets.PSWebCmdletV2` experimental feature is enabled, the exist
 This allows users to try out the new cmdlet and provide feedback then revert
 to the non-experimental version when needed.
 
-### Experimental Parameters in Cmdlets
+## Experimental Parameters in Cmdlets
 
 The `Experimental` attribute can also be applied to individual parameters. This
 allows you to create an experimental set of parameters for an existing cmdlet
@@ -170,4 +195,3 @@ if ([ExperimentalFeature]::IsEnabled("MyModule.MyExperimentalFeature"))
 [Disable-ExperimentalFeature](xref:Microsoft.PowerShell.Core.Disable-ExperimentalFeature)
 
 [Get-ExperimentalFeature](xref:Microsoft.PowerShell.Core.Get-ExperimentalFeature)
-

reference/7.2/Microsoft.PowerShell.Core/About/about_Experimental_Features.md

@@ -1,7 +1,7 @@
 ---
 description: The Experimental Features support in PowerShell provides a mechanism for experimental features to coexist with existing stable features in PowerShell or PowerShell modules.
 Locale: en-US
-ms.date: 03/13/2020
+ms.date: 11/15/2021
 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_experimental_features?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Experimental Features
@@ -48,7 +48,7 @@ specified and the only valid values are:
 - `Show` means to show this experimental feature if the feature is enabled
 - `Hide` means to hide this experimental feature if the feature is enabled
 
-### Declaring Experimental Features in Modules Written in C\#
+## Declaring Experimental Features in Modules Written in C\#
 
 Module authors who want to use the Experimental Feature flags can declare a
 cmdlet as experimental by using the `Experimental` attribute.
@@ -59,7 +59,7 @@ cmdlet as experimental by using the `Experimental` attribute.
 public class InvokeWebRequestCommandV2 : WebCmdletBaseV2 { ... }
 ```
 
-### Declaring Experimental Features in Modules written in PowerShell
+## Declaring Experimental Features in Modules written in PowerShell
 
 Module written in PowerShell can also use the `Experimental` attribute to
 declare experimental cmdlets:
@@ -73,7 +73,32 @@ function Enable-SSHRemoting {
 }
 ```
 
-### Mutually Exclusive Experimental Features
+Metadata about an experimental feature is kept in the module manifest. Use the
+`PrivateData.PSData.ExperimentalFeatures` property of a module manifest to
+expose the experimental features from the module. The `ExperimentalFeatures`
+property is an array of hashtables containing the name and description of the
+feature.
+
+For example:
+
+```powershell
+PrivateData = @{
+  PSData = @{
+    ExperimentalFeatures = @(
+      @{
+          Name = "PSWebCmdletV2"
+          Description = "Rewrite the web cmdlets for better performance"
+      },
+      @{
+          Name = "PSRestCmdletV2"
+          Description = "Rewrite the REST API cmdlets for better performance"
+      }
+    )
+  }
+}
+```
+
+## Mutually Exclusive Experimental Features
 
 There are cases where an experimental feature cannot co-exist side-by-side with
 an existing feature or another experimental feature.
@@ -108,7 +133,7 @@ When the `MyWebCmdlets.PSWebCmdletV2` experimental feature is enabled, the exist
 This allows users to try out the new cmdlet and provide feedback then revert
 to the non-experimental version when needed.
 
-### Experimental Parameters in Cmdlets
+## Experimental Parameters in Cmdlets
 
 The `Experimental` attribute can also be applied to individual parameters. This
 allows you to create an experimental set of parameters for an existing cmdlet
@@ -170,4 +195,3 @@ if ([ExperimentalFeature]::IsEnabled("MyModule.MyExperimentalFeature"))
 [Disable-ExperimentalFeature](xref:Microsoft.PowerShell.Core.Disable-ExperimentalFeature)
 
 [Get-ExperimentalFeature](xref:Microsoft.PowerShell.Core.Get-ExperimentalFeature)
-