Update code comments

Author: mickael-menu

Sources/Shared/Toolkit/Data/Container/Container.swift

@@ -8,7 +8,16 @@ import Foundation
 
 /// A container provides access to a list of `Resource` entries.
 public protocol Container: Closeable {
-    /// Direct source to this container, when available.
+    /// URL locating this container, when available.
+    ///
+    /// This can be used to optimize access to a container's content for the
+    /// caller. For example if the container is available on the local file
+    /// system, a caller might prefer using a file handle instead of the
+    /// ``Container`` API.
+    ///
+    /// Note that this must represent the same content available in
+    /// ``Container``. If you transform the resources content on the fly (e.g.
+    /// with ``TransformingContainer``), then the `sourceURL` becomes nil.
     var sourceURL: AbsoluteURL? { get }
 
     /// List of all the container entries.

Sources/Shared/Toolkit/Data/Resource/Resource.swift

@@ -8,7 +8,19 @@ import Foundation
 
 /// Acts as a proxy to an actual resource by handling read access.
 public protocol Resource: Streamable {
-    /// URL locating this resource, if any.
+    /// URL locating this resource, when available.
+    ///
+    /// This can be used to optimize access to a resource's content for the
+    /// caller. For example if the resource is available on the local file
+    /// system, a caller might prefer using a file handle instead of the
+    /// ``Resource`` API.
+    ///
+    /// Note that this must represent the same content available in
+    /// ``Resource``. If you transform the resources content on the fly (e.g.
+    /// with ``TransformingResource``), then the `sourceURL` becomes nil.
+    ///
+    /// A ``Resource`` located in a ZIP archive will have a nil `sourceURL`, as
+    /// there is no direct access to the ZIP entry using an absolute URL.
     var sourceURL: AbsoluteURL? { get }
 
     /// Properties associated to the resource.