Merge branch 'main' of https://github.com/nanoframework/CoreLibrary into develop

***NO_CI***

Author: josesimoes

Tests/NFUnitTestSystemLib/UnitTestGuid.cs

@@ -419,15 +419,29 @@ public void Ctor_UInt_UShort_UShort_Byte_Byte_Byte_Byte_Byte_Byte_Byte_Byte()
         [TestMethod]
         public void NewGuid()
         {
+            // generate a new Guid
             Guid guid1 = Guid.NewGuid();
 
+            OutputHelper.WriteLine($"Guid1: {guid1}");
+
+            // check that the guid is not empty
             Assert.AreNotEqual(Guid.Empty, guid1);
+            // check version 4
             Assert.IsTrue((guid1.ToByteArray()[7] & 0xF0) == 0x40);
+            // check variant
+            Assert.IsTrue((guid1.ToByteArray()[8] & 0xC0) == 0x80);
 
+            // go for another one
             Guid guid2 = Guid.NewGuid();
 
+            OutputHelper.WriteLine($"Guid2: {guid2}");
+
+            // check that the guid is not empty
             Assert.AreNotEqual(guid1, guid2);
+            // check version 4
             Assert.IsTrue((guid2.ToByteArray()[7] & 0xF0) == 0x40);
+            // check variant
+            Assert.IsTrue((guid2.ToByteArray()[8] & 0xC0) == 0x80);
         }
 
         [TestMethod]

nanoFramework.CoreLibrary/System/Guid.cs

@@ -190,6 +190,15 @@ public int CompareTo(object value)
         /// Returns a 16-element byte array that contains the value of this instance.
         /// </summary>
         /// <returns>A 16-element byte array.</returns>
+        /// <remarks>
+        /// <para>
+        /// You can use the byte array returned by this method to round-trip a Guid value by calling the <see cref="Guid(byte[])"/> constructor.
+        /// </para>
+        /// <para>
+        /// Note that the order of bytes in the returned byte array is different from the string representation of a Guid value.
+        /// The order of the beginning four-byte group and the next two two-byte groups is reversed, whereas the order of the last two-byte group and the closing six-byte group is the same.
+        /// </para>
+        /// </remarks>
         public byte[] ToByteArray()
         {
             byte[] buffer = new byte[16];