Improved XML docs for Image.WrapMemory APIs

src/ImageSharp/Image.WrapMemory.cs

@@ -18,6 +18,14 @@ namespace SixLabors.ImageSharp
         /// <summary>
         /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
         /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
+        /// The ownership of the underlying buffer for the input <see cref="Memory{T}"/> instance is not being transferred to
+        /// the new <see cref="Image{TPixel}"/> instance, meaning that consumers of this method need to make sure the input buffer
+        /// is either self-contianed (for instance, this is the case for a <see cref="Memory{T}"/> instance wrapping a new array that was
+        /// created), or that the owning object is not disposed until the returned <see cref="Image{TPixel}"/> is not disposed.
+        /// For instance, if the input <see cref="Memory{T}"/> instance is one retrieved from an <see cref="IMemoryOwner{T}"/> instance
+        /// rented from a memory pool (such as <see cref="MemoryPool{T}"/>), and that owning instance is disposed while the image is still
+        /// in use, this will lead to undefined behavior and possibly runtime crashes (as the same buffer might then be modified by other
+        /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers properly.
         /// </summary>
         /// <typeparam name="TPixel">The pixel type</typeparam>
         /// <param name="configuration">The <see cref="Configuration"/></param>
@@ -47,6 +55,14 @@ namespace SixLabors.ImageSharp
         /// <summary>
         /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
         /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
+        /// The ownership of the underlying buffer for the input <see cref="Memory{T}"/> instance is not being transferred to
+        /// the new <see cref="Image{TPixel}"/> instance, meaning that consumers of this method need to make sure the input buffer
+        /// is either self-contianed (for instance, this is the case for a <see cref="Memory{T}"/> instance wrapping a new array that was
+        /// created), or that the owning object is not disposed until the returned <see cref="Image{TPixel}"/> is not disposed.
+        /// For instance, if the input <see cref="Memory{T}"/> instance is one retrieved from an <see cref="IMemoryOwner{T}"/> instance
+        /// rented from a memory pool (such as <see cref="MemoryPool{T}"/>), and that owning instance is disposed while the image is still
+        /// in use, this will lead to undefined behavior and possibly runtime crashes (as the same buffer might then be modified by other
+        /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers properly.
         /// </summary>
         /// <typeparam name="TPixel">The pixel type</typeparam>
         /// <param name="configuration">The <see cref="Configuration"/></param>
@@ -66,7 +82,14 @@ namespace SixLabors.ImageSharp
         /// <summary>
         /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
         /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
-        /// The memory is being observed, the caller remains responsible for managing it's lifecycle.
+        /// The ownership of the underlying buffer for the input <see cref="Memory{T}"/> instance is not being transferred to
+        /// the new <see cref="Image{TPixel}"/> instance, meaning that consumers of this method need to make sure the input buffer
+        /// is either self-contianed (for instance, this is the case for a <see cref="Memory{T}"/> instance wrapping a new array that was
+        /// created), or that the owning object is not disposed until the returned <see cref="Image{TPixel}"/> is not disposed.
+        /// For instance, if the input <see cref="Memory{T}"/> instance is one retrieved from an <see cref="IMemoryOwner{T}"/> instance
+        /// rented from a memory pool (such as <see cref="MemoryPool{T}"/>), and that owning instance is disposed while the image is still
+        /// in use, this will lead to undefined behavior and possibly runtime crashes (as the same buffer might then be modified by other
+        /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers properly.
         /// </summary>
         /// <typeparam name="TPixel">The pixel type.</typeparam>
         /// <param name="pixelMemory">The pixel memory.</param>
@@ -156,6 +179,14 @@ namespace SixLabors.ImageSharp
         /// <summary>
         /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
         /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
+        /// The ownership of the underlying buffer for the input <see cref="Memory{T}"/> instance is not being transferred to
+        /// the new <see cref="Image{TPixel}"/> instance, meaning that consumers of this method need to make sure the input buffer
+        /// is either self-contianed (for instance, this is the case for a <see cref="Memory{T}"/> instance wrapping a new array that was
+        /// created), or that the owning object is not disposed until the returned <see cref="Image{TPixel}"/> is not disposed.
+        /// For instance, if the input <see cref="Memory{T}"/> instance is one retrieved from an <see cref="IMemoryOwner{T}"/> instance
+        /// rented from a memory pool (such as <see cref="MemoryPool{T}"/>), and that owning instance is disposed while the image is still
+        /// in use, this will lead to undefined behavior and possibly runtime crashes (as the same buffer might then be modified by other
+        /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers properly.
         /// </summary>
         /// <typeparam name="TPixel">The pixel type</typeparam>
         /// <param name="configuration">The <see cref="Configuration"/></param>
@@ -188,6 +219,14 @@ namespace SixLabors.ImageSharp
         /// <summary>
         /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
         /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
+        /// The ownership of the underlying buffer for the input <see cref="Memory{T}"/> instance is not being transferred to
+        /// the new <see cref="Image{TPixel}"/> instance, meaning that consumers of this method need to make sure the input buffer
+        /// is either self-contianed (for instance, this is the case for a <see cref="Memory{T}"/> instance wrapping a new array that was
+        /// created), or that the owning object is not disposed until the returned <see cref="Image{TPixel}"/> is not disposed.
+        /// For instance, if the input <see cref="Memory{T}"/> instance is one retrieved from an <see cref="IMemoryOwner{T}"/> instance
+        /// rented from a memory pool (such as <see cref="MemoryPool{T}"/>), and that owning instance is disposed while the image is still
+        /// in use, this will lead to undefined behavior and possibly runtime crashes (as the same buffer might then be modified by other
+        /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers properly.
         /// </summary>
         /// <typeparam name="TPixel">The pixel type</typeparam>
         /// <param name="configuration">The <see cref="Configuration"/></param>
@@ -207,7 +246,14 @@ namespace SixLabors.ImageSharp
         /// <summary>
         /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
         /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
-        /// The memory is being observed, the caller remains responsible for managing it's lifecycle.
+        /// The ownership of the underlying buffer for the input <see cref="Memory{T}"/> instance is not being transferred to
+        /// the new <see cref="Image{TPixel}"/> instance, meaning that consumers of this method need to make sure the input buffer
+        /// is either self-contianed (for instance, this is the case for a <see cref="Memory{T}"/> instance wrapping a new array that was
+        /// created), or that the owning object is not disposed until the returned <see cref="Image{TPixel}"/> is not disposed.
+        /// For instance, if the input <see cref="Memory{T}"/> instance is one retrieved from an <see cref="IMemoryOwner{T}"/> instance
+        /// rented from a memory pool (such as <see cref="MemoryPool{T}"/>), and that owning instance is disposed while the image is still
+        /// in use, this will lead to undefined behavior and possibly runtime crashes (as the same buffer might then be modified by other
+        /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers properly.
         /// </summary>
         /// <typeparam name="TPixel">The pixel type.</typeparam>
         /// <param name="byteMemory">The byte memory representing the pixel data.</param>
@@ -224,6 +270,19 @@ namespace SixLabors.ImageSharp
         /// <summary>
         /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
         /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
+        /// This method relies on callers to carefully manage the target memory area being referenced by the
+        /// pointer, and it requires that the lifetime of such a memory area is at least equal to that of the returned
+        /// <see cref="Image{TPixel}"/> instance. For instance, if the input pointer references an unmanaged memory area,
+        /// callers need to ensure that that memory area is not freed as long as the returned <see cref="Image{TPixel}"/> is
+        /// in use and not disposed. The same applies if the input memory area points to a pinned managed object, as callers
+        /// need to ensure that object will remain pinned as long as the <see cref="Image{TPixel}"/> instance is in use.
+        /// Failing to do so constitutes undefined behavior and will likely lead to memory corruption and runtime crashes.
+        /// Note that if you have a <see cref="Memory{T}"/> or an array (which can be cast to <see cref="Memory{T}"/>) of
+        /// either <see cref="byte"/> or <typeparamref name="TPixel"/> values, it is highly recommended to use one of the other
+        /// available overloads of this method instead (such as <see cref="WrapMemory{TPixel}(Configuration, Memory{byte}, int, int)"/>
+        /// or <see cref="WrapMemory{TPixel}(Configuration, Memory{TPixel}, int, int)"/>, to make the resulting code less error
+        /// prone and avoid having to pin the underlying memory buffer in use. This method is primarily meant to be used when
+        /// doing interop or working with buffers that are located in unmanaged memory.
         /// </summary>
         /// <typeparam name="TPixel">The pixel type</typeparam>
         /// <param name="configuration">The <see cref="Configuration"/></param>
@@ -255,6 +314,19 @@ namespace SixLabors.ImageSharp
         /// <summary>
         /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
         /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
+        /// This method relies on callers to carefully manage the target memory area being referenced by the
+        /// pointer, and it requires that the lifetime of such a memory area is at least equal to that of the returned
+        /// <see cref="Image{TPixel}"/> instance. For instance, if the input pointer references an unmanaged memory area,
+        /// callers need to ensure that that memory area is not freed as long as the returned <see cref="Image{TPixel}"/> is
+        /// in use and not disposed. The same applies if the input memory area points to a pinned managed object, as callers
+        /// need to ensure that object will remain pinned as long as the <see cref="Image{TPixel}"/> instance is in use.
+        /// Failing to do so constitutes undefined behavior and will likely lead to memory corruption and runtime crashes.
+        /// Note that if you have a <see cref="Memory{T}"/> or an array (which can be cast to <see cref="Memory{T}"/>) of
+        /// either <see cref="byte"/> or <typeparamref name="TPixel"/> values, it is highly recommended to use one of the other
+        /// available overloads of this method instead (such as <see cref="WrapMemory{TPixel}(Configuration, Memory{byte}, int, int)"/>
+        /// or <see cref="WrapMemory{TPixel}(Configuration, Memory{TPixel}, int, int)"/>, to make the resulting code less error
+        /// prone and avoid having to pin the underlying memory buffer in use. This method is primarily meant to be used when
+        /// doing interop or working with buffers that are located in unmanaged memory.
         /// </summary>
         /// <typeparam name="TPixel">The pixel type</typeparam>
         /// <param name="configuration">The <see cref="Configuration"/></param>
@@ -274,7 +346,19 @@ namespace SixLabors.ImageSharp
         /// <summary>
         /// Wraps an existing contiguous memory area of 'width' x 'height' pixels,
         /// allowing to view/manipulate it as an <see cref="Image{TPixel}"/> instance.
-        /// The memory is being observed, the caller remains responsible for managing it's lifecycle.
+        /// This method relies on callers to carefully manage the target memory area being referenced by the
+        /// pointer, and it requires that the lifetime of such a memory area is at least equal to that of the returned
+        /// <see cref="Image{TPixel}"/> instance. For instance, if the input pointer references an unmanaged memory area,
+        /// callers need to ensure that that memory area is not freed as long as the returned <see cref="Image{TPixel}"/> is
+        /// in use and not disposed. The same applies if the input memory area points to a pinned managed object, as callers
+        /// need to ensure that object will remain pinned as long as the <see cref="Image{TPixel}"/> instance is in use.
+        /// Failing to do so constitutes undefined behavior and will likely lead to memory corruption and runtime crashes.
+        /// Note that if you have a <see cref="Memory{T}"/> or an array (which can be cast to <see cref="Memory{T}"/>) of
+        /// either <see cref="byte"/> or <typeparamref name="TPixel"/> values, it is highly recommended to use one of the other
+        /// available overloads of this method instead (such as <see cref="WrapMemory{TPixel}(Configuration, Memory{byte}, int, int)"/>
+        /// or <see cref="WrapMemory{TPixel}(Configuration, Memory{TPixel}, int, int)"/>, to make the resulting code less error
+        /// prone and avoid having to pin the underlying memory buffer in use. This method is primarily meant to be used when
+        /// doing interop or working with buffers that are located in unmanaged memory.
         /// </summary>
         /// <typeparam name="TPixel">The pixel type.</typeparam>
         /// <param name="pointer">The pointer to the target memory buffer to wrap.</param>