Add comments for reviewed usage of pinned GCHandles. (#1290)

src/AudioToolbox/AudioConverter.cs

@@ -659,7 +659,7 @@ namespace XamCore.AudioToolbox
 				return null;
 
 			var data = new T [size / elementSize];
-			var array_handle = GCHandle.Alloc (data, GCHandleType.Pinned);
+			var array_handle = GCHandle.Alloc (data, GCHandleType.Pinned); // This requires a pinned GCHandle, since it's not possible to use unsafe code to get the address of a generic object.
 
 			try {
 				var ptr = array_handle.AddrOfPinnedObject ();

src/AudioToolbox/AudioFormatAvailability.cs

@@ -64,7 +64,7 @@ namespace XamCore.AudioToolbox {
 				return null;
 
 			var data = new T[size / Marshal.SizeOf (typeof (T))];
-			var array_handle = GCHandle.Alloc (data, GCHandleType.Pinned);
+			var array_handle = GCHandle.Alloc (data, GCHandleType.Pinned); // This requires a pinned GCHandle, since it's not possible to use unsafe code to get the address of a generic object.
 
 			try {
 				var ptr = array_handle.AddrOfPinnedObject ();

src/CoreGraphics/CGBitmapContext.cs

@@ -75,14 +75,14 @@ namespace XamCore.CoreGraphics {
 		public CGBitmapContext (byte [] data, nint width, nint height, nint bitsPerComponent, nint bytesPerRow, CGColorSpace colorSpace, CGImageAlphaInfo bitmapInfo)
 		{
 			if (data != null)
-				buffer = GCHandle.Alloc (data, GCHandleType.Pinned);
+				buffer = GCHandle.Alloc (data, GCHandleType.Pinned); // This requires a pinned GCHandle, because unsafe code is scoped to the current block, and the address of the byte array will be used after this function returns.
 			Handle = CGBitmapContextCreate (data, width, height, bitsPerComponent, bytesPerRow, GetHandle (colorSpace), (uint) bitmapInfo);
 		}
 
 		public CGBitmapContext (byte [] data, nint width, nint height, nint bitsPerComponent, nint bytesPerRow, CGColorSpace colorSpace, CGBitmapFlags bitmapInfo)
 		{
 			if (data != null)
-				buffer = GCHandle.Alloc (data, GCHandleType.Pinned);
+				buffer = GCHandle.Alloc (data, GCHandleType.Pinned); // This requires a pinned GCHandle, because unsafe code is scoped to the current block, and the address of the byte array will be used after this function returns.
 			Handle = CGBitmapContextCreate (data, width, height, bitsPerComponent, bytesPerRow, GetHandle (colorSpace), (uint) bitmapInfo);
 		}
 

src/CoreGraphics/CGDataProvider.cs

@@ -191,7 +191,7 @@ namespace XamCore.CoreGraphics {
 			if (offset + count > buffer.Length)
 				throw new ArgumentException ("offset");
 
-			var gch = GCHandle.Alloc (buffer, GCHandleType.Pinned);
+			var gch = GCHandle.Alloc (buffer, GCHandleType.Pinned); // This requires a pinned GCHandle, because unsafe code is scoped to the current block, and the address of the byte array will be used after this function returns.
 			var ptr = gch.AddrOfPinnedObject () + offset;
 			handle = CGDataProviderCreateWithData (GCHandle.ToIntPtr (gch), ptr, count, release_gchandle_callback);
 		}

src/CoreMedia/CMCustomBlockAllocator.cs

@@ -98,7 +98,7 @@ namespace XamCore.CoreMedia {
 		GCHandle dataHandle;
 		public CMManagedArrayBlockAllocator (byte [] data)
 		{
-			dataHandle = GCHandle.Alloc (data, GCHandleType.Pinned);
+			dataHandle = GCHandle.Alloc (data, GCHandleType.Pinned); // This requires a pinned GCHandle, because unsafe code is scoped to the current block, and the address of the byte array will be used after this function returns.
 		}
 
 		public override IntPtr Allocate (nuint sizeInBytes)

src/CoreMedia/CMFormatDescription.cs

@@ -467,7 +467,7 @@ namespace XamCore.CoreMedia {
 				var parameterSetPtrs = new IntPtr [parameterSets.Count];
 
 				for (int i = 0; i < parameterSets.Count; i++) {
-					handles [i] = GCHandle.Alloc (parameterSets [i], GCHandleType.Pinned);
+					handles [i] = GCHandle.Alloc (parameterSets [i], GCHandleType.Pinned); // This can't use unsafe code because we need to get the pointer for an unbound number of objects.
 					parameterSetPtrs [i] = handles [i].AddrOfPinnedObject ();
 					parameterSetSizes [i] = (nuint)parameterSets [i].Length;
 				}

src/CoreVideo/CVPixelBuffer.cs

@@ -200,7 +200,7 @@ namespace XamCore.CoreVideo {
 			if (data.Length < height * bytesPerRow)
 				throw new ArgumentOutOfRangeException (nameof (data), "The length of data is smaller than height * bytesPerRow");
 
-			gchandle = GCHandle.Alloc (data, GCHandleType.Pinned);
+			gchandle = GCHandle.Alloc (data, GCHandleType.Pinned); // This requires a pinned GCHandle, because unsafe code is scoped to the current block, and the address of the byte array will be used after this function returns.
 
 			status = CVPixelBufferCreateWithBytes (IntPtr.Zero, width, height, pixelFormatType, gchandle.AddrOfPinnedObject (), bytesPerRow, releaseBytesCallback, GCHandle.ToIntPtr (gchandle), DictionaryContainerHelper.GetHandle (pixelBufferAttributes), out handle);
 
@@ -296,7 +296,7 @@ namespace XamCore.CoreVideo {
 			data = new PlaneData ();
 			data.dataHandles = new GCHandle [planeCount];
 			for (int i = 0; i < planeCount; i++) {
-				data.dataHandles[i] = GCHandle.Alloc (planes [i], GCHandleType.Pinned);
+				data.dataHandles[i] = GCHandle.Alloc (planes [i], GCHandleType.Pinned); // This can't use unsafe code because we need to get the pointer for an unbound number of objects.
 				addresses[i] = data.dataHandles[i].AddrOfPinnedObject ();
 			}
 			data_handle = GCHandle.Alloc (data);

src/Metal/MTLDevice.cs

@@ -47,7 +47,7 @@ namespace XamCore.Metal {
 	public static partial class MTLDevice_Extensions {
 		public static IMTLBuffer CreateBuffer<T> (this IMTLDevice This, T [] data, MTLResourceOptions options) where T : struct
 		{
-			var handle = GCHandle.Alloc (data, GCHandleType.Pinned);
+			var handle = GCHandle.Alloc (data, GCHandleType.Pinned); // This requires a pinned GCHandle, since it's not possible to use unsafe code to get the address of a generic object.
 			try {
 				IntPtr ptr = handle.AddrOfPinnedObject ();
 				return This.CreateBuffer (ptr, (nuint)(data.Length * Marshal.SizeOf (typeof (T))) , options);
@@ -58,7 +58,7 @@ namespace XamCore.Metal {
 
 		public static IMTLBuffer CreateBufferNoCopy<T> (this IMTLDevice This, T [] data, MTLResourceOptions options, MTLDeallocator deallocator) where T : struct
 		{
-			var handle = GCHandle.Alloc (data, GCHandleType.Pinned);
+			var handle = GCHandle.Alloc (data, GCHandleType.Pinned); // This requires a pinned GCHandle, since it's not possible to use unsafe code to get the address of a generic object.
 			try {
 				IntPtr ptr = handle.AddrOfPinnedObject ();
 				return This.CreateBufferNoCopy (ptr, (nuint)(data.Length * Marshal.SizeOf (typeof (T))) , options, deallocator);