From f95688d41118bd042b43b2e6e4f2a8dec1e254a7 Mon Sep 17 00:00:00 2001
From: Patrick8639 <planz@ordinasoft.ch>
Date: Tue, 21 May 2024 09:06:16 +0200
Subject: [PATCH 1/4] feat: permits to specify the placement of overwrites

Related https://github.com/dotnet/docfx/discussions/9908
Related https://github.com/dotnet/docfx/issues/7648
---
 .../EntityMergers/MergePlacement.cs           | 33 ++++++++++++++
 .../EntityMergers/ReflectionEntityMerger.cs   | 45 +++++++++++++++++++
 src/Docfx.Common/IItemWithMetadata.cs         | 20 +++++++++
 .../ManagedReference/Models/ItemViewModel.cs  |  2 +-
 4 files changed, 99 insertions(+), 1 deletion(-)
 create mode 100644 src/Docfx.Common/EntityMergers/MergePlacement.cs
 create mode 100644 src/Docfx.Common/IItemWithMetadata.cs

diff --git a/src/Docfx.Common/EntityMergers/MergePlacement.cs b/src/Docfx.Common/EntityMergers/MergePlacement.cs
new file mode 100644
index 00000000000..44c92c44ad7
--- /dev/null
+++ b/src/Docfx.Common/EntityMergers/MergePlacement.cs
@@ -0,0 +1,33 @@
+// Licensed to the .NET Foundation under one or more agreements.\r
+// The .NET Foundation licenses this file to you under the MIT license.
+
+
+namespace Docfx.Common.EntityMergers;
+
+
+/// <summary>
+///   The placement for a merge.
+/// </summary>
+internal enum MergePlacement
+{
+
+    /// <summary>
+    ///   The placement is not specified.
+    /// </summary>
+    None,
+
+    /// <summary>
+    ///   The override must be placed after the original content.
+    /// </summary>
+    After,
+
+    /// <summary>
+    ///   The override must be placed before the original content.
+    /// </summary>
+    Before,
+
+    /// <summary>
+    ///   The override must replace the original content.
+    /// </summary>
+    Replace
+}
diff --git a/src/Docfx.Common/EntityMergers/ReflectionEntityMerger.cs b/src/Docfx.Common/EntityMergers/ReflectionEntityMerger.cs
index 3854d88600b..9b81e4067fc 100644
--- a/src/Docfx.Common/EntityMergers/ReflectionEntityMerger.cs
+++ b/src/Docfx.Common/EntityMergers/ReflectionEntityMerger.cs
@@ -80,8 +80,53 @@ public void Merge(ref object source, object overrides, IMergeContext context)
             {
                 return;
             }
+
+
+            // Gets the placement of the override
+            var placement = MergePlacement.None;
+
+            {
+                if (overrides is IItemWithMetadata ovr
+                    && ovr.Metadata.TryGetValue("placement", out var placementValue))
+                {
+                    placement =
+                        placementValue switch
+                        {
+                            "after"   => MergePlacement.After,
+                            "before"  => MergePlacement.Before,
+                            "replace" => MergePlacement.Replace,
+                            _         => MergePlacement.None
+                        };
+                }
+            }
+
+
             foreach (var prop in Props)
             {
+
+                // Placement specified in the override file
+                if (placement != MergePlacement.None
+                    && prop.Prop.Name is "Remarks" or "Summary")
+                {
+                    var o = prop.Prop.GetValue(overrides);
+
+                    if (o is null)
+                        continue;
+
+                    var s = prop.Prop.GetValue(source);
+
+                    s = placement switch
+                    {
+                        MergePlacement.After   => $"{s}{o}",
+                        MergePlacement.Before  => $"{o}{s}",
+                        MergePlacement.Replace => o.ToString()
+                    };
+
+                    prop.Prop.SetValue(source, s);
+                }
+
+
+                // Placement specified in the property
                 switch (prop.Option)
                 {
                     case MergeOption.Merge:
diff --git a/src/Docfx.Common/IItemWithMetadata.cs b/src/Docfx.Common/IItemWithMetadata.cs
new file mode 100644
index 00000000000..c77526ce571
--- /dev/null
+++ b/src/Docfx.Common/IItemWithMetadata.cs
@@ -0,0 +1,20 @@
+// Licensed to the .NET Foundation under one or more agreements.\r
+// The .NET Foundation licenses this file to you under the MIT license.
+
+
+namespace Docfx.Common;
+
+
+/// <summary>
+///   An item that contains metadate
+/// </summary>
+public interface IItemWithMetadata
+{
+
+    /// <summary>
+    ///   Gets the metadata.
+    /// </summary>
+    /// <value>The metadata.</value>
+    Dictionary<string, object> Metadata { get; }
+
+}
diff --git a/src/Docfx.Dotnet/ManagedReference/Models/ItemViewModel.cs b/src/Docfx.Dotnet/ManagedReference/Models/ItemViewModel.cs
index dac1880ed40..e740c12868a 100644
--- a/src/Docfx.Dotnet/ManagedReference/Models/ItemViewModel.cs
+++ b/src/Docfx.Dotnet/ManagedReference/Models/ItemViewModel.cs
@@ -13,7 +13,7 @@
 
 namespace Docfx.DataContracts.ManagedReference;
 
-public class ItemViewModel : IOverwriteDocumentViewModel
+public class ItemViewModel : IOverwriteDocumentViewModel, IItemWithMetadata
 {
     [YamlMember(Alias = Constants.PropertyName.Uid)]
     [JsonProperty(Constants.PropertyName.Uid)]

From 1a3fb3520314cb15215898b6a277e869654eef0e Mon Sep 17 00:00:00 2001
From: Patrick8639 <planz@ordinasoft.ch>
Date: Fri, 24 May 2024 16:24:55 +0200
Subject: [PATCH 2/4] Corrected a small bug after refactoring.

---
 src/Docfx.Common/EntityMergers/ReflectionEntityMerger.cs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/Docfx.Common/EntityMergers/ReflectionEntityMerger.cs b/src/Docfx.Common/EntityMergers/ReflectionEntityMerger.cs
index 9b81e4067fc..505d307c55b 100644
--- a/src/Docfx.Common/EntityMergers/ReflectionEntityMerger.cs
+++ b/src/Docfx.Common/EntityMergers/ReflectionEntityMerger.cs
@@ -123,6 +123,8 @@ public void Merge(ref object source, object overrides, IMergeContext context)
                     };
 
                     prop.Prop.SetValue(source, s);
+
+                    continue;
                 }
 
 

From d554ccb46fee842ed7d7e549f4052c70b59541c1 Mon Sep 17 00:00:00 2001
From: Patrick8639 <planz@ordinasoft.ch>
Date: Tue, 28 May 2024 13:45:10 +0200
Subject: [PATCH 3/4] IItemWithMetadata is now internal.

---
 src/Docfx.Common/Docfx.Common.csproj  | 6 ++++++
 src/Docfx.Common/IItemWithMetadata.cs | 2 +-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/Docfx.Common/Docfx.Common.csproj b/src/Docfx.Common/Docfx.Common.csproj
index 46d7bccbca5..ae45de1376d 100644
--- a/src/Docfx.Common/Docfx.Common.csproj
+++ b/src/Docfx.Common/Docfx.Common.csproj
@@ -7,4 +7,10 @@
     <ProjectReference Include="..\Docfx.Plugins\Docfx.Plugins.csproj" />
     <ProjectReference Include="..\Docfx.YamlSerialization\Docfx.YamlSerialization.csproj" />
   </ItemGroup>
+
+  <ItemGroup>
+    <InternalsVisibleTo Include="Docfx.Build.ManagedReference"/>
+    <InternalsVisibleTo Include="Docfx.Dotnet"/>
+  </ItemGroup>
+
 </Project>
diff --git a/src/Docfx.Common/IItemWithMetadata.cs b/src/Docfx.Common/IItemWithMetadata.cs
index c77526ce571..8968a3552a8 100644
--- a/src/Docfx.Common/IItemWithMetadata.cs
+++ b/src/Docfx.Common/IItemWithMetadata.cs
@@ -8,7 +8,7 @@ namespace Docfx.Common;
 /// <summary>
 ///   An item that contains metadate
 /// </summary>
-public interface IItemWithMetadata
+internal interface IItemWithMetadata
 {
 
     /// <summary>

From 9ff1f6947593e2f51598c3bdc5e2eca3a083e718 Mon Sep 17 00:00:00 2001
From: Patrick8639 <planz@ordinasoft.ch>
Date: Thu, 30 May 2024 10:28:52 +0200
Subject: [PATCH 4/4] PolySharp is no more active for Docfx.Common

---
 Directory.Build.props | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Directory.Build.props b/Directory.Build.props
index e0900528b67..cddf0d2c372 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -45,7 +45,7 @@
     <None Include="$(MSBuildThisFileDirectory)\README.md" Pack="true" PackagePath="\"/>
   </ItemGroup>
 
-  <ItemGroup>
+  <ItemGroup Condition="'$(ProjectName)' != 'Docfx.Common'">
     <PackageReference Include="PolySharp">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>