Generating docs in a dotnet fashion (#103)

* New way of documenting stuff

I was not having it anymore, the docs just have to be inside the c# code, possibly as xml comments (the dotnet way).

Hence the fact that I just released [pwsh-docs](https://www.nuget.org/packages/SvRooij.PowerShell.Docs#readme-body-tab) a dotnet tool that will help you create the maml file from the dll and the written xml docs.

src/Svrooij.WinTuner.CmdLets/Commands/ConnectWtWinTuner.cs

@@ -14,19 +14,42 @@ namespace Svrooij.WinTuner.CmdLets.Commands;
 /// <summary>
 /// <para type="synopsis">Connect to Intune</para>
 /// <para type="description">A separate command to select the correct authentication provider, you no longer have to provide the auth parameters with each command.</para>
-/// <para type="link" uri="https://wintuner.app/docs/wintuner-powershell/Connect-WtWinTuner">Documentation</para> 
 /// </summary>
+/// <psOrder>3</psOrder>
+/// <parameterSet>
+/// <para type="name">Interactive</para>
+/// <para type="description">If you're running WinTuner on your local machine, you can use the interactive browser login. This will integrate with the native browser based login screen on Windows and with the default browser on other platforms.</para>
+/// </parameterSet>
+/// <parameterSet>
+/// <para type="name">UseManagedIdentity</para>
+/// <para type="description">WinTuner supports Managed Identity authentication, this is the recommended way if you run WinTuner in the Azure Environment.</para>
+/// </parameterSet>
+/// <parameterSet>
+/// <para type="name">UseDefaultCredentials</para>
+/// <para type="description">A more extended version of the Managed Identity is the Default Credentials, this will use the [DefaultAzureCredential](https://learn.microsoft.com/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet&amp;wt.mc_id=SEC-MVP-5004985), from the `Azure.Identity` package. This will try several methods to authenticate, Environment Variables, Managed Identity, Azure CLI and more.</para>
+/// </parameterSet>
+/// <parameterSet>
+/// <para type="name">Token</para>
+/// <para type="description">Let's say you have a token from another source, just hand us to token and we'll use it to connect to Intune. This token has a limited lifetime, so you'll be responsible for refreshing it.</para>
+/// </parameterSet>
+/// <parameterSet>
+/// <para type="name">ClientCredentials</para>
+/// <para type="description">:::warning Last resort\r\nUsing client credentials is not recommended because you'll have to keep the secret, **secret**!\r\n\r\nPlease let us know if you have to use this method, we might be able to help you with a better solution.\r\n:::</para>
+/// </parameterSet>
 /// <example>
-/// <para type="description">Connect using interactive authentication</para>
+/// <para type="name">Connect using interactive authentication</para>
+/// <para type="description">This will trigger a login broker popup (Windows Hello) on Windows and the default browser on other platforms</para>
 /// <code>Connect-WtWinTuner -Username "[email protected]"</code>
 /// </example>
 /// <example>
-/// <para type="description">Connect using managed identity</para>
+/// <para type="name">Connect using managed identity</para>
+/// <para type="description">Try to connect using a managed identity on the current platform, obviously only works in Azure.</para>
 /// <code>Connect-WtWinTuner -UseManagedIdentity</code>
 /// </example>
 /// <example>
-/// <para type="description">Connect using default credentials</para>
-/// <code>az login &amp; Connect-WtWinTuner -UseDefaultCredentials</code>
+/// <para type="name">Connect using default credentials</para>
+/// <para type="description">A chain of credentials is tried until one succeeds. Including Environment Variables, Managed Identity, Visual Studio (code) and Azure CLI</para>
+/// <code>az login\r\nConnect-WtWinTuner -UseDefaultCredentials</code>
 /// </example>
 [Cmdlet(VerbsCommunications.Connect, "WtWinTuner", DefaultParameterSetName = ParamSetInteractive, HelpUri = "https://wintuner.app/docs/wintuner-powershell/Connect-WtWinTuner")]
 [Alias("Connect-WinTuner")]
@@ -161,15 +184,40 @@ public class ConnectWtWinTuner : DependencyCmdlet<Startup>
     [Parameter(
         Mandatory = false,
         Position = 10,
+        ParameterSetName = ParamSetClientCredentials,
+        ValueFromPipeline = false,
+        ValueFromPipelineByPropertyName = false,
+        HelpMessage = "Specify the scopes to request, default is `https://graph.microsoft.com/.default`")]
+    [Parameter(
+        Mandatory = false,
+        Position = 10,
+        ParameterSetName = nameof(UseDefaultCredentials),
+        ValueFromPipeline = false,
+        ValueFromPipelineByPropertyName = false,
+        HelpMessage = "Specify the scopes to request, default is `https://graph.microsoft.com/.default`")]
+    [Parameter(
+        Mandatory = false,
+        Position = 10,
+        ParameterSetName = nameof(UseManagedIdentity),
+        ValueFromPipeline = false,
+        ValueFromPipelineByPropertyName = false,
+        HelpMessage = "Specify the scopes to request, default is `https://graph.microsoft.com/.default`")]
+    [Parameter(
+        Mandatory = false,
+        Position = 10,
+        ParameterSetName = ParamSetInteractive,
         ValueFromPipeline = false,
         ValueFromPipelineByPropertyName = false,
         HelpMessage = "Specify the scopes to request, default is `DeviceManagementConfiguration.ReadWrite.All`, `DeviceManagementApps.ReadWrite.All`")]
     public string[]? Scopes { get; set; } = Environment.GetEnvironmentVariable("AZURE_SCOPES")?.Split(' ');
 
     /// <summary>
-    /// Try getting a token after connecting.
+    /// Immediately try to get a token.
     /// </summary>
-    [Parameter(Mandatory = false, Position = 11, HelpMessage = "Try to get a token after connecting, useful for testing.")]
+    [Parameter(Mandatory = false, Position = 11, ParameterSetName = nameof(UseManagedIdentity), HelpMessage = "Immediately try to get a token.")]
+    [Parameter(Mandatory = false, Position = 11, ParameterSetName = ParamSetInteractive, HelpMessage = "Immediately try to get a token.")]
+    [Parameter(Mandatory = false, Position = 11, ParameterSetName = nameof(UseDefaultCredentials), HelpMessage = "Immediately try to get a token.")]
+    [Parameter(Mandatory = false, Position = 11, ParameterSetName = ParamSetClientCredentials, HelpMessage = "Immediately try to get a token.")]
     public SwitchParameter Test { get; set; }
 
     [ServiceDependency]

src/Svrooij.WinTuner.CmdLets/Commands/DeployWtMsStoreApp.cs

@@ -2,7 +2,6 @@
 using Svrooij.PowerShell.DependencyInjection;
 using System;
 using System.Management.Automation;
-using System.Net.Http;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Kiota.Abstractions.Authentication;
@@ -13,12 +12,21 @@
 namespace Svrooij.WinTuner.CmdLets.Commands;
 /// <summary>
 /// <para type="synopsis">Create a MsStore app in Intune</para>
-/// <para type="description">Use this command to create an Microsoft Store app in Microsoft Intune</para>
-/// <para type="link" uri="https://wintuner.app/docs/wintuner-powershell/Deploy-WtMsStoreApp">Documentation</para> 
+/// <para type="description">Use this command to create an Microsoft Store app in Microsoft Intune.\r\n\r\nThis is an [**authenticated command**](./authentication), so call [Connect-WtWinTuner](./Connect-WtWinTuner) before calling this command.</para>
 /// </summary>
+/// <psOrder>20</psOrder>
+/// <parameterSet>
+/// <para type="name">PackageId</para>
+/// <para type="description">Deploy an app to Intune by specifying the package ID of the app in the Microsoft Store.</para>
+/// </parameterSet>
+/// <parameterSet>
+/// <para type="name">SearchQuery</para>
+/// <para type="description">Deploy an app to Intune by searching for packages and pick the first one, use carefully!</para>
+/// </parameterSet>
 /// <example>
-/// <para type="description">Add Firefox to Intune</para>
-/// <code>Deploy-WtMsStoreApp -PackageId 9NZVDKPMR9RD</code>
+/// <para type="name">Add Firefox to Intune</para>
+/// <para type="description">Add Firefox to Intune and make available for `AllUsers`</para>
+/// <code>Deploy-WtMsStoreApp -PackageId &quot;9NZVDKPMR9RD&quot; -AvailableFor AllUsers</code>
 /// </example>
 [Cmdlet(VerbsLifecycle.Deploy, "WtMsStoreApp", DefaultParameterSetName = nameof(PackageId), HelpUri = "https://wintuner.app/docs/wintuner-powershell/Deploy-WtMsStoreApp")]
 [OutputType(typeof(GraphModels.WinGetApp))]
@@ -52,28 +60,32 @@ public class DeployWtMsStoreApp : BaseIntuneCmdlet
     /// <para type="description">Categories to add to the app</para>
     /// </summary>
     [Parameter(Mandatory = false,
+        Position = 1,
         HelpMessage = "Categories to add to the app")]
     public string[]? Categories { get; set; }
 
     /// <summary>
-    /// <para type="description">Groups that the app should available for, Group Object ID or 'AllUsers'/'AllDevices'</para>
+    /// <para type="description">Groups that the app should available for, Group Object ID or `AllUsers` / `AllDevices`</para>
     /// </summary>
     [Parameter(Mandatory = false,
-               HelpMessage = "Groups that the app should available for, Group Object ID or 'AllUsers'/'AllDevices'")]
+        Position = 2,
+        HelpMessage = "Groups that the app should available for, Group Object ID or `AllUsers` / `AllDevices`")]
     public string[]? AvailableFor { get; set; }
 
     /// <summary>
-    /// <para type="description">Groups that the app is required for, Group Object ID or 'AllUsers'/'AllDevices'</para>
+    /// <para type="description">Groups that the app is required for, Group Object ID or `AllUsers` / `AllDevices`</para>
     /// </summary>
     [Parameter(Mandatory = false,
-                      HelpMessage = "Groups that the app is required for, Group Object ID or 'AllUsers'/'AllDevices'")]
+        Position = 3,
+                      HelpMessage = "Groups that the app is required for, Group Object ID or `AllUsers` / `AllDevices`")]
     public string[]? RequiredFor { get; set; }
 
     /// <summary>
-    /// <para type="description">Groups that the app should be uninstalled for, Group Object ID or 'AllUsers'/'AllDevices'</para>
+    /// <para type="description">Groups that the app should be uninstalled for, Group Object ID or `AllUsers` / `AllDevices`</para>
     /// </summary>
     [Parameter(Mandatory = false,
-                             HelpMessage = "Groups that the app should be uninstalled for, Group Object ID or 'AllUsers'/'AllDevices'")]
+        Position = 4,
+        HelpMessage = "Groups that the app should be uninstalled for, Group Object ID or `AllUsers` / `AllDevices`")]
     public string[]? UninstallFor { get; set; }
 
     [ServiceDependency]

src/Svrooij.WinTuner.CmdLets/Commands/DeployWtWin32App.cs

@@ -16,14 +16,32 @@
 namespace Svrooij.WinTuner.CmdLets.Commands;
 /// <summary>
 /// <para type="synopsis">Create a Win32Lob app in Intune</para>
-/// <para type="description">Use this command to upload an intunewin package to Microsoft Intune as a new Win32LobApp.</para>
-/// <para type="link" uri="https://wintuner.app/docs/wintuner-powershell/Deploy-WtWin32App">Documentation</para> 
+/// <para type="description">Use this command to upload an intunewin package to Microsoft Intune as a new Win32LobApp.\r\n\r\nThis is an [**authenticated command**](./authentication), so call [Connect-WtWinTuner](./Connect-WtWinTuner) before calling this command.</para>
 /// </summary>
+/// <psOrder>11</psOrder>
+/// <parameterSet>
+/// <para type="name">WinGet</para>
+/// <para type="description">Deploy an app packaged by WinTuner. If you used the [New-WtWingetPackage](./New-WtWingetPackage) commandlet to create the package, there will be some metadata available to us that is needed to create the Win32App in Intune.</para>
+/// </parameterSet>
+/// <parameterSet>
+/// <para type="name">Win32LobApp</para>
+/// <para type="description">Deploy an application, by specifying all the needed properties of the `Win32LobApp` and an IntuneWinFile.</para>
+/// </parameterSet>
+/// <parameterSet>
+/// <para type="name">PackageFolder</para>
+/// <para type="description">Deploy a pre-packaged application, from just it's folder</para>
+/// </parameterSet>
 /// <example>
-/// <para type="description">Upload a pre-packaged application, from just it's folder</para>
-/// <code>Deploy-WtWin32App -PackageFolder C:\Tools\packages\JanDeDobbeleer.OhMyPosh\19.5.2</code>
+/// <para type="name">Deploy OhMyPosh</para>
+/// <para type="description">OhMyPosh v19.5.0 is packaged to this folder, now deploy it to Azure</para>
+/// <code>Deploy-WtWin32App -PackageFolder &quot;C:\Tools\packages\JanDeDobbeleer.OhMyPosh\19.5.2&quot;</code>
 /// </example>
-[Cmdlet(VerbsLifecycle.Deploy, "WtWin32App", DefaultParameterSetName = ParameterSetApp, HelpUri = "https://wintuner.app/docs/wintuner-powershell/Deploy-WtWin32App")]
+/// <example>
+/// <para type="name">Package and deploy OhMyPosh</para>
+/// <para type="description">Combining both the `New-WtWinGetPackage` and the `Deploy-WtWin32App` command, and making it available to All Users</para>
+/// <code>New-WtWingetPackage -PackageId JanDeDobbeleer.OhMyPosh -PackageFolder C:\Tools\Packages | Deploy-WtWin32App -Available AllUsers</code>
+/// </example>
+[Cmdlet(VerbsLifecycle.Deploy, "WtWin32App", DefaultParameterSetName = ParameterSetWinGet, HelpUri = "https://wintuner.app/docs/wintuner-powershell/Deploy-WtWin32App")]
 [OutputType(typeof(GraphModels.Win32LobApp))]
 public class DeployWtWin32App : BaseIntuneCmdlet
 {
@@ -115,42 +133,46 @@ public class DeployWtWin32App : BaseIntuneCmdlet
     /// <summary>
     /// Override the name of the app in Intune
     /// </summary>
-    [Parameter(HelpMessage = "Override the name of the app in Intune", Mandatory = false)]
+    [Parameter(HelpMessage = "Override the name of the app in Intune", Position = 100, Mandatory = false)]
     public string? OverrideAppName { get; set; }
 
     /// <summary>
     /// <para type="description">The graph id of the app to supersede</para>
     /// </summary>
-    [Parameter(DontShow = true, HelpMessage = "Graph ID of the app to supersede", Mandatory = false)]
+    [Parameter(DontShow = true, HelpMessage = "Graph ID of the app to supersede", Position = 30, Mandatory = false)]
     [Alias("AppId")]
     public string? GraphId { get; set; }
 
     /// <summary>
     /// <para type="description">Categories to add to the app</para>
     /// </summary>
     [Parameter(Mandatory = false,
+        Position = 11,
         HelpMessage = "Categories to add to the app")]
     public string[]? Categories { get; set; }
 
     /// <summary>
-    /// <para type="description">Groups that the app should available for, Group Object ID or 'AllUsers'/'AllDevices'</para>
+    /// <para type="description">Groups that the app should available for, Group Object ID or `AllUsers` / `AllDevices`</para>
     /// </summary>
     [Parameter(Mandatory = false,
-               HelpMessage = "Groups that the app should available for, Group Object ID or 'AllUsers'/'AllDevices'")]
+        Position = 12,
+               HelpMessage = "Groups that the app should available for, Group Object ID or `AllUsers` / `AllDevices`")]
     public string[]? AvailableFor { get; set; }
 
     /// <summary>
-    /// <para type="description">Groups that the app is required for, Group Object ID or 'AllUsers'/'AllDevices'</para>
+    /// <para type="description">Groups that the app is required for, Group Object ID or `AllUsers` / `AllDevices`</para>
     /// </summary>
     [Parameter(Mandatory = false,
-                      HelpMessage = "Groups that the app is required for, Group Object ID or 'AllUsers'/'AllDevices'")]
+        Position = 13,
+                      HelpMessage = "Groups that the app is required for, Group Object ID or `AllUsers` / `AllDevices`")]
     public string[]? RequiredFor { get; set; }
 
     /// <summary>
-    /// <para type="description">Groups that the app should be uninstalled for, Group Object ID or 'AllUsers'/'AllDevices'</para>
+    /// <para type="description">Groups that the app should be uninstalled for, Group Object ID or `AllUsers` / `AllDevices`</para>
     /// </summary>
     [Parameter(Mandatory = false,
-                             HelpMessage = "Groups that the app should be uninstalled for, Group Object ID or 'AllUsers'/'AllDevices'")]
+        Position = 14,
+                             HelpMessage = "Groups that the app should be uninstalled for, Group Object ID or `AllUsers` / `AllDevices`")]
     public string[]? UninstallFor { get; set; }
 
     [ServiceDependency]

src/Svrooij.WinTuner.CmdLets/Commands/DisconnectWtWinTuner.cs

@@ -8,8 +8,13 @@ namespace Svrooij.WinTuner.CmdLets.Commands;
 /// <summary>
 /// <para type="synopsis">Clear authentication data from module</para>
 /// <para type="description">You can call Connect-WtWinTuner which will keep security things in memory, to be able to clear things we made this command</para>
-/// <para type="link" uri="https://wintuner.app/docs/wintuner-powershell/Disconnect-WtWinTuner">Documentation</para> 
 /// </summary>
+/// <psOrder>4</psOrder>
+/// <example>
+/// <para type="name">Logout</para>
+/// <para type="description">This will remove all credentials from the memory</para>
+/// <code>Disconnect-WtWinTuner</code>
+/// </example>
 [Cmdlet(VerbsCommunications.Disconnect, "WtWinTuner", HelpUri = "https://wintuner.app/docs/wintuner-powershell/Disconnect-WtWinTuner")]
 [Alias("Disconnect-WinTuner")]
 public class DisconnectWtWinTuner : DependencyCmdlet<Startup>

src/Svrooij.WinTuner.CmdLets/Commands/GetWtToken.cs

@@ -10,10 +10,11 @@ namespace Svrooij.WinTuner.CmdLets.Commands;
 
 /// <summary>
 /// <para type="synopsis">Get a token for graph</para>
-/// <para type="description">This command will get a token for the graph api. The token is cached, so you can call this as often as you want.</para>
-/// <para type="link" uri="https://wintuner.app/docs/wintuner-powershell/Get-WtToken">Documentation</para>
+/// <para type="description">This command will get a token for the graph api. The token is cached, so you can call this as often as you want.\r\n\r\nThis is an [**authenticated command**](./authentication), so call [Connect-WtWinTuner](./Connect-WtWinTuner) before calling this command.</para>
 /// </summary>
+/// <psOrder>100</psOrder>
 /// <example>
+/// <para type="name">Get a token</para>
 /// <para type="description">Get token, show details and copy to clipboard</para>
 /// <code>Get-WtToken -DecodeToken | Set-Clipboard</code>
 /// </example>