feat: permits to specify the placement of overwrites

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>

src/Docfx.Common/Docfx.Common.csproj

@@ -8,6 +8,11 @@
     <ProjectReference Include="..\Docfx.YamlSerialization\Docfx.YamlSerialization.csproj" />
   </ItemGroup>
 
+  <ItemGroup>
+    <InternalsVisibleTo Include="Docfx.Build.ManagedReference"/>
+    <InternalsVisibleTo Include="Docfx.Dotnet"/>
+  </ItemGroup>
+
   <!-- TODO: Following settings will be removed after NewtonsoftJson dependencies are removed. -->
   <ItemGroup>
     <InternalsVisibleTo Include="docfx.Build" />

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
+}

src/Docfx.Common/EntityMergers/ReflectionEntityMerger.cs

@@ -80,8 +80,55 @@ 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);
+
+                    continue;
+                }
+
+
+                // Placement specified in the property
                 switch (prop.Option)
                 {
                     case MergeOption.Merge:

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>
+internal interface IItemWithMetadata
+{
+
+    /// <summary>
+    ///   Gets the metadata.
+    /// </summary>
+    /// <value>The metadata.</value>
+    Dictionary<string, object> Metadata { get; }
+
+}

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)]