From 34b0e374d855cacde830c91b7251f74d499d1a1d Mon Sep 17 00:00:00 2001
From: Dan Balasescu <smoogipoo@smgi.me>
Date: Fri, 3 Dec 2021 21:29:20 +0900
Subject: [PATCH] Add serialisation/deserialisation explanation

---
 osu.Desktop/LegacyIpc/LegacyIpcMessage.cs     | 13 +++++++++++++
 osu.Desktop/LegacyIpc/LegacyTcpIpcProvider.cs |  1 +
 2 files changed, 14 insertions(+)

diff --git a/osu.Desktop/LegacyIpc/LegacyIpcMessage.cs b/osu.Desktop/LegacyIpc/LegacyIpcMessage.cs
index 6fefae4509..0fa60e2068 100644
--- a/osu.Desktop/LegacyIpc/LegacyIpcMessage.cs
+++ b/osu.Desktop/LegacyIpc/LegacyIpcMessage.cs
@@ -2,11 +2,24 @@
 // See the LICENCE file in the repository root for full licence text.
 
 using osu.Framework.Platform;
+using Newtonsoft.Json.Linq;
 
 namespace osu.Desktop.LegacyIpc
 {
     /// <summary>
     /// An <see cref="IpcMessage"/> that can be used to communicate to and from legacy clients.
+    /// <para>
+    /// In order to deserialise types at either end, types must be serialised as their <see cref="System.Type.AssemblyQualifiedName"/>,
+    /// however this cannot be done since osu!stable and osu!lazer live in two different assemblies.
+    /// <br />
+    /// To get around this, this class exists which serialises a payload (<see cref="LegacyIpcMessage.Data"/>) as an <see cref="System.Object"/> type,
+    /// which can be deserialised at either end because it is part of the core library (mscorlib / System.Private.CorLib).
+    /// The payload contains the data to be sent over the IPC channel.
+    /// <br />
+    /// At either end, Json.NET deserialises the payload into a <see cref="JObject"/> which is manually converted back into the expected <see cref="LegacyIpcMessage.Data"/> type,
+    /// which then further contains another <see cref="JObject"/> representing the data sent over the IPC channel whose type can likewise be lazily matched through
+    /// <see cref="LegacyIpcMessage.Data.MessageType"/>.
+    /// </para>
     /// </summary>
     /// <remarks>
     /// Synchronise any changes with osu-stable.
diff --git a/osu.Desktop/LegacyIpc/LegacyTcpIpcProvider.cs b/osu.Desktop/LegacyIpc/LegacyTcpIpcProvider.cs
index e42a10430a..97a4c57bf0 100644
--- a/osu.Desktop/LegacyIpc/LegacyTcpIpcProvider.cs
+++ b/osu.Desktop/LegacyIpc/LegacyTcpIpcProvider.cs
@@ -36,6 +36,7 @@ namespace osu.Desktop.LegacyIpc
                     logger.Add("Processing legacy IPC message...");
                     logger.Add($"    {msg.Value}", LogLevel.Debug);
 
+                    // See explanation in LegacyIpcMessage for why this is done this way.
                     var legacyData = ((JObject)msg.Value).ToObject<LegacyIpcMessage.Data>();
                     object value = parseObject((JObject)legacyData!.MessageData, legacyData.MessageType);