docs: generate XML docs from moby sources

Directory.Build.props

@@ -1,6 +1,7 @@
 <Project>
   <PropertyGroup>
     <LangVersion>latest</LangVersion>
+    <DockerVersion>v29.1.5</DockerVersion>
   </PropertyGroup>
   <!-- Strong-naming -->
   <PropertyGroup Label="Signing">

src/Directory.Build.props

@@ -13,6 +13,7 @@
         <PublishRepositoryUrl>true</PublishRepositoryUrl>
         <IncludeSymbols>true</IncludeSymbols>
         <EmbedUntrackedSources>true</EmbedUntrackedSources>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
         <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
         <PackageLicenseExpression>MIT</PackageLicenseExpression>
         <PackageIcon>icon.png</PackageIcon>
@@ -21,6 +22,7 @@
 
     <PropertyGroup>
         <Nullable>enable</Nullable>
+        <NoWarn>$(NoWarn);CS1573;CS1591</NoWarn>
     </PropertyGroup>
 
     <PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">

src/Docker.DotNet/Docker.DotNet.csproj

@@ -2,7 +2,7 @@
   <PropertyGroup>
     <AssemblyName>Docker.DotNet</AssemblyName>
     <PackageId>Docker.DotNet.Enhanced</PackageId>
-    <Description>A .NET client for the Docker Engine API with fully asynchronous, non-blocking, object-oriented APIs.</Description>
+    <Description>A .NET client for the Docker Engine API ($(DockerVersion)) with fully asynchronous, non-blocking, object-oriented APIs.</Description>
   </PropertyGroup>
   <ItemGroup>
     <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />

src/Docker.DotNet/Endpoints/IConfigsOperations.cs

@@ -9,6 +9,7 @@ public interface IConfigOperations
     /// 200 - No error.
     /// 500 - Server error.
     /// </remarks>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task<IList<SwarmConfig>> ListConfigsAsync(CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -20,6 +21,7 @@ public interface IConfigOperations
     /// 409 - Name conflicts with an existing object.
     /// 500 - Server error.
     /// </remarks>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task<SwarmCreateConfigResponse> CreateConfigAsync(SwarmCreateConfigParameters body, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -32,6 +34,7 @@ public interface IConfigOperations
     /// 500 - Server error.
     /// </remarks>
     /// <param name="id">ID of the config.</param>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task<SwarmConfig> InspectConfigAsync(string id, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -43,5 +46,6 @@ public interface IConfigOperations
     /// 500 - Server error.
     /// </remarks>
     /// <param name="id">ID of the config.</param>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task RemoveConfigAsync(string id, CancellationToken cancellationToken = default);
 }

src/Docker.DotNet/Endpoints/IImageOperations.cs

@@ -20,7 +20,7 @@ public interface IImageOperations
     /// </summary>
     /// <param name="contents">A readable tar stream of file contents for the build.</param>
     /// <param name="parameters">Specifics of how to perform the operation.</param>
-    /// <param name="authConfig">Information for authenticating with the registry.</param>
+    /// <param name="authConfigs">Information for authenticating with the registry.</param>
     /// <param name="headers">Additional headers to include in the HTTP request to the registry.</param>
     /// <param name="progress">Provides a delegate the receives progress updates while the operation is underway.</param>
     /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
@@ -195,7 +195,6 @@ public interface IImageOperations
     /// <remarks>
     /// The equivalent commands in the Docker CLI are <c>docker tag</c> and <c>docker image tag</c>.
     /// </remarks>
-    /// <param name="name">Image name or id.</param>
     /// <exception cref="ArgumentNullException">One or more of the inputs was <see langword="null"/>.</exception>
     /// <exception cref="DockerImageNotFoundException">No such image was found.</exception>
     /// <exception cref="DockerApiException">There was a conflict, or the input is invalid, or the daemon experienced an error.</exception>
@@ -214,7 +213,6 @@ public interface IImageOperations
     /// <br/>
     /// The equivalent commands in the Docker CLI are <c>docker inspect</c> and <c>docker image inspect</c>.
     /// </remarks>
-    /// <param name="name">Image name or id.</param>
     /// <exception cref="ArgumentNullException">One or more of the inputs was <see langword="null"/>.</exception>
     /// <exception cref="DockerImageNotFoundException">No such image was found.</exception>
     /// <exception cref="DockerApiException">There was a conflict, or the input is invalid, or the daemon experienced an error.</exception>
@@ -269,7 +267,6 @@ public interface IImageOperations
     /// <remarks>
     /// The equivalent command in the Docker CLI is <c>docker export</c>.
     /// </remarks>
-    /// <param name="name">Image name or ID.</param>
     /// <seealso cref="SaveImagesAsync(string[], CancellationToken)"/>
     /// <exception cref="ArgumentNullException">One or more of the inputs was <see langword="null"/>.</exception>
     /// <exception cref="DockerApiException">There was a conflict, or the input is invalid, or the daemon experienced an error.</exception>
@@ -290,7 +287,6 @@ public interface IImageOperations
     /// <br/>
     /// The equivalent command in the Docker CLI is <c>docker export</c>.
     /// </remarks>
-    /// <param name="names">Image names to filter by.</param>
     /// <seealso cref="SaveImageAsync(string, CancellationToken)"/>
     /// <exception cref="ArgumentNullException">One or more of the inputs was <see langword="null"/>.</exception>
     /// <exception cref="DockerApiException">There was a conflict, or the input is invalid, or the daemon experienced an error.</exception>

src/Docker.DotNet/Endpoints/INetworkOperations.cs

@@ -11,6 +11,7 @@ public interface INetworkOperations
     /// 200 - No error.
     /// 500 - Server error.
     /// </remarks>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task<IList<NetworkResponse>> ListNetworksAsync(NetworksListParameters? parameters = null, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -23,6 +24,7 @@ public interface INetworkOperations
     /// 404 - Network not found.
     /// </remarks>
     /// <param name="id">Network ID or name.</param>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task<NetworkResponse> InspectNetworkAsync(string id, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -36,6 +38,7 @@ public interface INetworkOperations
     /// 500 - Server error.
     /// </remarks>
     /// <param name="id">Network ID or name.</param>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task DeleteNetworkAsync(string id, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -49,6 +52,7 @@ public interface INetworkOperations
     /// 404 - Plugin not found.
     /// 500 - Server error.
     /// </remarks>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task<NetworksCreateResponse> CreateNetworkAsync(NetworksCreateParameters parameters, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -63,6 +67,7 @@ public interface INetworkOperations
     /// 500 - Server error.
     /// </remarks>
     /// <param name="id">Network ID or name.</param>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task ConnectNetworkAsync(string id, NetworkConnectParameters parameters, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -77,12 +82,12 @@ public interface INetworkOperations
     /// 404 - Network or container not found.
     /// 500 - Server error.
     /// </remarks>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task DisconnectNetworkAsync(string id, NetworkDisconnectParameters parameters, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Delete unused networks.
     /// </summary>
-    /// <param name="id">Network ID or name.</param>
     /// <remarks>
     /// docker network disconnect
     ///
@@ -93,13 +98,13 @@ public interface INetworkOperations
     /// 404 - Network or container not found.
     /// 500 - Server error.
     /// </remarks>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     [Obsolete("Use INetworkOperations.PruneNetworksAsync")]
     Task DeleteUnusedNetworksAsync(NetworksDeleteUnusedParameters? parameters = null, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Delete unused networks.
     /// </summary>
-    /// <param name="id">Network ID or name.</param>
     /// <remarks>
     /// docker network disconnect
     ///
@@ -110,5 +115,6 @@ public interface INetworkOperations
     /// 404 - Network or container not found.
     /// 500 - Server error.
     /// </remarks>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task<NetworksPruneResponse> PruneNetworksAsync(NetworksDeleteUnusedParameters? parameters = null, CancellationToken cancellationToken = default);
 }

src/Docker.DotNet/Endpoints/IPluginOperations.cs

@@ -15,6 +15,7 @@ public interface IPluginOperations
     /// 200 - No error.
     /// 500 - Server error.
     /// </remarks>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task<IList<Plugin>> ListPluginsAsync(PluginListParameters? parameters = null, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -28,6 +29,7 @@ public interface IPluginOperations
     /// 200 - No error.
     /// 500 - Server error.
     /// </remarks>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task<IList<PluginPrivilege>> GetPrivilegesAsync(PluginGetPrivilegeParameters parameters, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -43,6 +45,7 @@ public interface IPluginOperations
     /// 204 - No error.
     /// 500 - Server error.
     /// </remarks>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task InstallPluginAsync(PluginInstallParameters parameters, IProgress<JSONMessage> progress, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -58,6 +61,7 @@ public interface IPluginOperations
     /// 500 - Server error.
     /// </remarks>
     /// <param name="name">The name of the plugin. The `:latest` tag is optional, and is the default if omitted.</param>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task<Plugin> InspectPluginAsync(string name, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -73,6 +77,7 @@ public interface IPluginOperations
     /// 500 - Server error.
     /// </remarks>
     /// <param name="name">The name of the plugin. The `:latest` tag is optional, and is the default if omitted.</param>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task RemovePluginAsync(string name, PluginRemoveParameters? parameters = null, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -88,6 +93,7 @@ public interface IPluginOperations
     /// 500 - Server error.
     /// </remarks>
     /// <param name="name">The name of the plugin. The `:latest` tag is optional, and is the default if omitted.</param>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task EnablePluginAsync(string name, PluginEnableParameters? parameters = null, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -103,6 +109,7 @@ public interface IPluginOperations
     /// 500 - Server error.
     /// </remarks>
     /// <param name="name">The name of the plugin. The `:latest` tag is optional, and is the default if omitted.</param>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task DisablePluginAsync(string name, PluginDisableParameters? parameters = null, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -118,6 +125,7 @@ public interface IPluginOperations
     /// 500 - Server error.
     /// </remarks>
     /// <param name="name">The name of the plugin. The `:latest` tag is optional, and is the default if omitted.</param>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task UpgradePluginAsync(string name, PluginUpgradeParameters parameters, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -131,6 +139,7 @@ public interface IPluginOperations
     /// 200 - No error.
     /// 500 - Server error.
     /// </remarks>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task CreatePluginAsync(PluginCreateParameters parameters, Stream plugin, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -148,6 +157,7 @@ public interface IPluginOperations
     /// 500 - Server error.
     /// </remarks>
     /// <param name="name">The name of the plugin. The `:latest` tag is optional, and is the default if omitted.</param>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task PushPluginAsync(string name, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -163,5 +173,6 @@ public interface IPluginOperations
     /// 500 - Server error.
     /// </remarks>
     /// <param name="name">The name of the plugin. The `:latest` tag is optional, and is the default if omitted.</param>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task ConfigurePluginAsync(string name, PluginConfigureParameters parameters, CancellationToken cancellationToken = default);
 }

src/Docker.DotNet/Endpoints/ISecretsOperations.cs

@@ -9,6 +9,7 @@ public interface ISecretsOperations
     /// 200 - No error.
     /// 500 - Server error.
     /// </remarks>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task<IList<Secret>> ListAsync(CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -20,6 +21,7 @@ public interface ISecretsOperations
     /// 409 - Name conflicts with an existing object.
     /// 500 - Server error.
     /// </remarks>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task<SecretCreateResponse> CreateAsync(SwarmSecretSpec body, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -32,6 +34,7 @@ public interface ISecretsOperations
     /// 500 - Server error.
     /// </remarks>
     /// <param name="id">ID of the secret.</param>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task<Secret> InspectAsync(string id, CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -43,5 +46,6 @@ public interface ISecretsOperations
     /// 500 - Server error.
     /// </remarks>
     /// <param name="id">ID of the secret.</param>
+    /// <param name="cancellationToken">When triggered, the operation will stop at the next available time, if possible.</param>
     Task DeleteAsync(string id, CancellationToken cancellationToken = default);
 }