Add basic documentation to most public cmdlets and types

app/Pog/lib_compiled/Pog/src/Commands/Common/CmdletProgressBar.cs

@@ -3,7 +3,7 @@
 
 namespace Pog.Commands.Common;
 
-public sealed class CmdletProgressBar : IDisposable {
+internal sealed class CmdletProgressBar : IDisposable {
     // when progress print activity ID is not set explicitly, use an auto-incrementing ID
     //  to show multiple progress bars when multiple cmdlets are ran in parallel
     private static int _nextActivityId = 0;
@@ -36,6 +36,7 @@ public void Dispose() {
         _progressRecord.RecordType = ProgressRecordType.Completed;
         _writeProgressFn(_progressRecord);
     }
-
-    public record struct ProgressActivity(string? Activity = null, string? Description = null, int? Id = null);
 }
+
+/// Metadata for rendering a PowerShell progress bar.
+public record struct ProgressActivity(string? Activity = null, string? Description = null, int? Id = null);

app/Pog/lib_compiled/Pog/src/Commands/ContainerCommands/AddEnvVarCommand.cs

@@ -6,6 +6,11 @@
 
 namespace Pog.Commands.ContainerCommands;
 
+/// <summary>Adds a value to a semicolon-delimited list in an environment variable.</summary>
+/// <para>
+/// This cmdlet is commonly used for inserting a directory path into `$env:PATH` or `$env:PSModulePath`.
+/// By default, the value is appended. To prepend the value (this typically gives it the highest priority), use `-Prepend`.
+/// </para>
 [PublicAPI]
 [Cmdlet(VerbsCommon.Add, "EnvVar")]
 public sealed class AddEnvVarCommand : PogCmdlet {

app/Pog/lib_compiled/Pog/src/Commands/ContainerCommands/DisableDisplayScalingCommand.cs

@@ -6,6 +6,12 @@
 
 namespace Pog.Commands.ContainerCommands;
 
+/// <summary>Disables system display scaling for the specified executable.</summary>
+/// <para>
+/// By default, Windows apply bitmap scaling to applications that do not explicitly declare that they perform scaling
+/// internally. For fractional scaling ratios, this results in blurry text in older apps. This cmdlet changes the application
+/// manifest to disable any system display scaling.
+/// </para>
 [PublicAPI]
 [Cmdlet(VerbsLifecycle.Disable, "DisplayScaling")]
 public sealed class DisableDisplayScalingCommand : PogCmdlet {

app/Pog/lib_compiled/Pog/src/Commands/ContainerCommands/GetUrlHashCommand.cs

@@ -39,7 +39,7 @@ protected override void ProcessRecord() {
     }
 
     private string GetUrlSha256Hash(Uri requestUri, UserAgentType userAgent, CancellationToken token) {
-        using var progressBar = new CmdletProgressBar(this, new CmdletProgressBar.ProgressActivity {
+        using var progressBar = new CmdletProgressBar(this, new ProgressActivity {
             Activity = "Retrieving file hash",
             Description = $"Downloading '{requestUri}'...",
         });

app/Pog/lib_compiled/Pog/src/Commands/ContainerCommands/RemoveEnvVarEntryCommand.cs

@@ -7,6 +7,10 @@
 
 namespace Pog.Commands.ContainerCommands;
 
+/// <summary>Removes a value from a semicolon-delimited list in an environment variable.</summary>
+/// <para>
+/// This cmdlet is commonly used for removing a directory path from `$env:PATH` or `$env:PSModulePath`.
+/// </para>
 [PublicAPI]
 [Cmdlet(VerbsCommon.Remove, "EnvVarEntry")]
 public sealed class RemoveEnvVarEntryCommand : PogCmdlet {

app/Pog/lib_compiled/Pog/src/Commands/ContainerCommands/SetEnvVarCommand.cs

@@ -5,6 +5,7 @@
 
 namespace Pog.Commands.ContainerCommands;
 
+/// <summary>Sets the specified user-level environment variable to a new value.</summary>
 [PublicAPI]
 [Cmdlet(VerbsCommon.Set, "EnvVar")]
 public sealed class SetEnvVarCommand : PogCmdlet {

app/Pog/lib_compiled/Pog/src/Commands/GetPogRepositoryCommand.cs

@@ -6,7 +6,7 @@
 
 namespace Pog.Commands;
 
-/// Returns the refs (paths/URLs) of all used package repositories.
+/// <summary>Returns the refs (paths/URLs) of all configured package repositories for this PowerShell instance.</summary>
 [PublicAPI]
 [Cmdlet(VerbsCommon.Get, "PogRepository")]
 [OutputType(typeof(string))]

app/Pog/lib_compiled/Pog/src/Commands/InternalCommands/ExpandArchive7ZipCommand.cs

@@ -17,7 +17,7 @@ public sealed class ExpandArchive7ZipCommand : PogCmdlet {
     [Parameter(Mandatory = true, Position = 1)] public string TargetPath = null!;
     /// If passed, only paths inside the archive matching at least one of the filters are extracted.
     [Parameter] public string[]? Filter;
-    [Parameter] public CmdletProgressBar.ProgressActivity ProgressActivity = new();
+    [Parameter] public ProgressActivity ProgressActivity = new();
 
     protected override void BeginProcessing() {
         base.BeginProcessing();

app/Pog/lib_compiled/Pog/src/Commands/InternalCommands/GetFileHash7ZipCommand.cs

@@ -12,7 +12,7 @@ namespace Pog.Commands.InternalCommands;
 public sealed class GetFileHash7ZipCommand : PogCmdlet {
     [Parameter(Mandatory = true, Position = 0)] public string LiteralPath = null!;
     [Parameter(Position = 1)] public GetFileHash7Zip.HashAlgorithm Algorithm = default;
-    [Parameter] public CmdletProgressBar.ProgressActivity ProgressActivity = new();
+    [Parameter] public ProgressActivity ProgressActivity = new();
 
     protected override void BeginProcessing() {
         base.BeginProcessing();

app/Pog/lib_compiled/Pog/src/Commands/InternalCommands/InvokeFileDownloadCommand.cs

@@ -15,7 +15,7 @@ public sealed class InvokeFileDownloadCommand : PogCmdlet {
     [Parameter(Mandatory = true, Position = 0)] public string SourceUrl = null!;
     [Parameter(Mandatory = true, Position = 1)] public string DestinationDirPath = null!;
     [Parameter] public DownloadParameters DownloadParameters = new();
-    [Parameter] public CmdletProgressBar.ProgressActivity ProgressActivity = new();
+    [Parameter] public ProgressActivity ProgressActivity = new();
 
     protected override void BeginProcessing() {
         base.BeginProcessing();

app/Pog/lib_compiled/Pog/src/Commands/SetPogRepositoryCommand.cs

@@ -5,7 +5,7 @@
 
 namespace Pog.Commands;
 
-/// Selects the package repository used by other commands.
+/// <summary>Sets the package repository used by other commands.</summary>
 /// <remarks>
 /// Not thread-safe. Do not call this concurrently with other Pog cmdlets from different runspaces, since some cmdlets
 /// internally repeatedly access the repository and assume it won't change between accesses.

app/Pog/lib_compiled/Pog/src/ImportedPackage/Pog.ImportedPackage.cs

@@ -11,12 +11,11 @@ public class ImportedPackageNotFoundException(string message) : PackageNotFoundE
 
 public class InvalidPackageRootException(string message) : ArgumentException(message);
 
-/// <summary>
-/// A class representing an imported package.
-///
+/// <summary>Class representing an installed package.</summary>
+/// <remarks>
 /// By default, the package manifest is loaded during initialization - the package must exist and have a valid manifest,
 /// otherwise an exception is thrown.
-/// </summary>
+/// </remarks>
 [PublicAPI]
 public sealed class ImportedPackage : Package, ILocalPackage {
     public PackageVersion? Version => Manifest.Version;

app/Pog/lib_compiled/Pog/src/InnerCommands/ExpandArchive7Zip.cs

@@ -19,7 +19,7 @@ public sealed class ExpandArchive7Zip(PogCmdlet cmdlet) : VoidCommand(cmdlet), I
     [Parameter] public string? RawTargetPath;
     /// If passed, only paths inside the archive matching at least one of the filters are extracted.
     [Parameter] public string[]? Filter = null;
-    [Parameter] public CmdletProgressBar.ProgressActivity ProgressActivity = new();
+    [Parameter] public ProgressActivity ProgressActivity = new();
 
     private string[]? _filterPatterns;
     private Process? _process;

app/Pog/lib_compiled/Pog/src/InnerCommands/GetFileHash7Zip.cs

@@ -14,7 +14,7 @@ public sealed class GetFileHash7Zip(PogCmdlet cmdlet) : ScalarCommand<string>(cm
     [Parameter(Mandatory = true)] public string Path = null!;
     [Parameter] public HashAlgorithm Algorithm = default;
 
-    [Parameter] public CmdletProgressBar.ProgressActivity ProgressActivity = new();
+    [Parameter] public ProgressActivity ProgressActivity = new();
 
     private string _algorithmStr = null!;
     private Process? _process;

app/Pog/lib_compiled/Pog/src/InnerCommands/InvokeCachedFileDownload.cs

@@ -34,7 +34,7 @@ internal class InvokeCachedFileDownload(PogCmdlet cmdlet) : ScalarCommand<Shared
     [Parameter(Mandatory = true)] public DownloadParameters DownloadParameters = null!;
     [Parameter(Mandatory = true)] public Package Package = null!;
     [Parameter] public bool StoreInCache = false;
-    [Parameter] public CmdletProgressBar.ProgressActivity ProgressActivity = new();
+    [Parameter] public ProgressActivity ProgressActivity = new();
 
     // TODO: handle `InvalidCacheEntryException` everywhere
     public override SharedFileCache.IFileLock Invoke() {

app/Pog/lib_compiled/Pog/src/InnerCommands/InvokeFileDownload.cs

@@ -15,7 +15,7 @@ internal sealed class InvokeFileDownload(PogCmdlet cmdlet) : ScalarCommand<strin
     [Parameter(Mandatory = true)] public string SourceUrl = null!;
     [Parameter(Mandatory = true)] public string DestinationDirPath = null!;
     [Parameter(Mandatory = true)] public DownloadParameters DownloadParameters = null!;
-    [Parameter] public CmdletProgressBar.ProgressActivity ProgressActivity = new();
+    [Parameter] public ProgressActivity ProgressActivity = new();
 
     /// <summary>Downloads the file from $SourceUrl to $DestinationDirPath.</summary>
     /// <returns>Full path of the downloaded file.</returns>

app/Pog/lib_compiled/Pog/src/Pog.Package.cs

@@ -6,6 +6,8 @@ namespace Pog;
 
 public class PackageNotFoundException(string message) : DirectoryNotFoundException(message);
 
+/// Base class for all kinds of packages, both installed (<see cref="ImportedPackage"/>) or available from
+/// a repository (<see cref="RepositoryPackage"/>).
 public abstract class Package {
     public readonly string PackageName;
     public abstract bool Exists {get;}

app/Pog/lib_compiled/Pog/src/RepositoryTypes.cs

@@ -124,6 +124,7 @@ public virtual RepositoryPackage GetVersionPackage(PackageVersion version, bool
     }
 }
 
+/// Class representing a package available for installation from a repository (either local or remote).
 [PublicAPI]
 public abstract class RepositoryPackage(RepositoryVersionedPackage parent, PackageVersion version)
         : Package(parent.PackageName, null) {