Fix S.R.InteropServices remarks (dotnet#71683)

Moved the triple slash seealso items outside of the remarks section, to prevent porting them to dotnet-api-docs, because they would show weird in MS Docs.
doorxp · Jul 6, 2022 · c5c4347 · c5c4347
1 parent 907f395
commit c5c4347
Show file tree

Hide file tree

Showing 8 changed files with 6 additions and 72 deletions.
diff --git a/...em.Private.CoreLib/src/System/Runtime/InteropServices/Marshalling/AnsiStringMarshaller.cs b/...em.Private.CoreLib/src/System/Runtime/InteropServices/Marshalling/AnsiStringMarshaller.cs
@@ -32,8 +32,8 @@ public AnsiStringMarshaller(string? str)
         /// <remarks>
         /// The <paramref name="buffer"/> must not be movable - that is, it should not be
         /// on the managed heap or it should be pinned.
-        /// <seealso cref="CustomTypeMarshallerFeatures.CallerAllocatedBuffer"/>
         /// </remarks>
+        /// <seealso cref="CustomTypeMarshallerFeatures.CallerAllocatedBuffer"/>
         public AnsiStringMarshaller(string? str, Span<byte> buffer)
         {
             _allocated = false;
@@ -65,18 +65,14 @@ public AnsiStringMarshaller(string? str, Span<byte> buffer)
         /// <summary>
         /// Returns the native value representing the string.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.TwoStageMarshalling"/>
-        /// </remarks>
         public byte* ToNativeValue() => _nativeValue;
 
         /// <summary>
         /// Sets the native value representing the string.
         /// </summary>
         /// <param name="value">The native value.</param>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.TwoStageMarshalling"/>
-        /// </remarks>
         public void FromNativeValue(byte* value)
         {
             _nativeValue = value;
@@ -86,17 +82,13 @@ public void FromNativeValue(byte* value)
         /// <summary>
         /// Returns the managed string.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerDirection.Out"/>
-        /// </remarks>
         public string? ToManaged() => Marshal.PtrToStringAnsi((IntPtr)_nativeValue);
 
         /// <summary>
         /// Frees native resources.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.UnmanagedResources"/>
-        /// </remarks>
         public void FreeNative()
         {
             if (_allocated)

diff --git a/.../System.Private.CoreLib/src/System/Runtime/InteropServices/Marshalling/ArrayMarshaller.cs b/.../System.Private.CoreLib/src/System/Runtime/InteropServices/Marshalling/ArrayMarshaller.cs
@@ -50,8 +50,8 @@ public ArrayMarshaller(T[]? array, int sizeOfNativeElement)
         /// <remarks>
         /// The <paramref name="buffer"/> must not be movable - that is, it should not be
         /// on the managed heap or it should be pinned.
-        /// <seealso cref="CustomTypeMarshallerFeatures.CallerAllocatedBuffer"/>
         /// </remarks>
+        /// <seealso cref="CustomTypeMarshallerFeatures.CallerAllocatedBuffer"/>
         public ArrayMarshaller(T[]? array, Span<byte> buffer, int sizeOfNativeElement)
         {
             _allocatedMemory = default;
@@ -83,29 +83,23 @@ public ArrayMarshaller(T[]? array, Span<byte> buffer, int sizeOfNativeElement)
         /// Gets a span that points to the memory where the managed values of the array are stored.
         /// </summary>
         /// <returns>Span over managed values of the array.</returns>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerDirection.In"/>
-        /// </remarks>
         public ReadOnlySpan<T> GetManagedValuesSource() => _managedArray;
 
         /// <summary>
         /// Gets a span that points to the memory where the unmarshalled managed values of the array should be stored.
         /// </summary>
         /// <param name="length">Length of the array.</param>
         /// <returns>Span where managed values of the array should be stored.</returns>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerDirection.Out"/>
-        /// </remarks>
         public Span<T> GetManagedValuesDestination(int length) => _allocatedMemory == IntPtr.Zero ? null : _managedArray = new T[length];
 
         /// <summary>
         /// Returns a span that points to the memory where the native values of the array are stored after the native call.
         /// </summary>
         /// <param name="length">Length of the array.</param>
         /// <returns>Span over the native values of the array.</returns>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerDirection.Out"/>
-        /// </remarks>
         public ReadOnlySpan<byte> GetNativeValuesSource(int length)
         {
             if (_allocatedMemory == IntPtr.Zero)
@@ -120,9 +114,7 @@ public ReadOnlySpan<byte> GetNativeValuesSource(int length)
         /// Returns a span that points to the memory where the native values of the array should be stored.
         /// </summary>
         /// <returns>Span where native values of the array should be stored.</returns>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerDirection.In"/>
-        /// </remarks>
         public Span<byte> GetNativeValuesDestination() => _span;
 
         /// <summary>
@@ -133,18 +125,14 @@ public ReadOnlySpan<byte> GetNativeValuesSource(int length)
         /// <summary>
         /// Returns the native value representing the array.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.TwoStageMarshalling"/>
-        /// </remarks>
         public byte* ToNativeValue() => (byte*)Unsafe.AsPointer(ref GetPinnableReference());
 
         /// <summary>
         /// Sets the native value representing the array.
         /// </summary>
         /// <param name="value">The native value.</param>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.TwoStageMarshalling"/>
-        /// </remarks>
         public void FromNativeValue(byte* value)
         {
             _allocatedMemory = (IntPtr)value;
@@ -153,17 +141,13 @@ public void FromNativeValue(byte* value)
         /// <summary>
         /// Returns the managed array.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerDirection.Out"/>
-        /// </remarks>
         public T[]? ToManaged() => _managedArray;
 
         /// <summary>
         /// Frees native resources.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.UnmanagedResources"/>
-        /// </remarks>
         public void FreeNative()
         {
             Marshal.FreeCoTaskMem(_allocatedMemory);

diff --git a/...em.Private.CoreLib/src/System/Runtime/InteropServices/Marshalling/BStrStringMarshaller.cs b/...em.Private.CoreLib/src/System/Runtime/InteropServices/Marshalling/BStrStringMarshaller.cs
@@ -34,8 +34,8 @@ public BStrStringMarshaller(string? str)
         /// <remarks>
         /// The <paramref name="buffer"/> must not be movable - that is, it should not be
         /// on the managed heap or it should be pinned.
-        /// <seealso cref="CustomTypeMarshallerFeatures.CallerAllocatedBuffer"/>
         /// </remarks>
+        /// <seealso cref="CustomTypeMarshallerFeatures.CallerAllocatedBuffer"/>
         public BStrStringMarshaller(string? str, Span<ushort> buffer)
         {
             _allocated = false;
@@ -78,18 +78,14 @@ public BStrStringMarshaller(string? str, Span<ushort> buffer)
         /// <summary>
         /// Returns the native value representing the string.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.TwoStageMarshalling"/>
-        /// </remarks>
         public void* ToNativeValue() => _ptrToFirstChar;
 
         /// <summary>
         /// Sets the native value representing the string.
         /// </summary>
         /// <param name="value">The native value.</param>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.TwoStageMarshalling"/>
-        /// </remarks>
         public void FromNativeValue(void* value)
         {
             _ptrToFirstChar = value;
@@ -99,9 +95,7 @@ public void FromNativeValue(void* value)
         /// <summary>
         /// Returns the managed string.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerDirection.Out"/>
-        /// </remarks>
         public string? ToManaged()
         {
             if (_ptrToFirstChar is null)
@@ -113,9 +107,7 @@ public void FromNativeValue(void* value)
         /// <summary>
         /// Frees native resources.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.UnmanagedResources"/>
-        /// </remarks>
         public void FreeNative()
         {
             if (_allocated)

diff --git a/...e.CoreLib/src/System/Runtime/InteropServices/Marshalling/CustomTypeMarshallerAttribute.cs b/...e.CoreLib/src/System/Runtime/InteropServices/Marshalling/CustomTypeMarshallerAttribute.cs
@@ -9,8 +9,8 @@ namespace System.Runtime.InteropServices.Marshalling
     /// <remarks>
     /// This attribute is recognized by the runtime-provided source generators for source-generated interop scenarios.
     /// It is not used by the interop marshalling system at runtime.
-    /// <seealso cref="LibraryImportAttribute"/>
     /// </remarks>
+    /// <seealso cref="LibraryImportAttribute"/>
     [AttributeUsage(AttributeTargets.Struct)]
     public sealed class CustomTypeMarshallerAttribute : Attribute
     {

diff --git a/...rivate.CoreLib/src/System/Runtime/InteropServices/Marshalling/CustomTypeMarshallerKind.cs b/...rivate.CoreLib/src/System/Runtime/InteropServices/Marshalling/CustomTypeMarshallerKind.cs
@@ -10,9 +10,7 @@ namespace System.Runtime.InteropServices.Marshalling
     /// <summary>
     /// The shape of a custom type marshaller for usage in source-generated interop scenarios.
     /// </summary>
-    /// <remarks>
     /// <seealso cref="LibraryImportAttribute"/>
-    /// </remarks>
     public enum CustomTypeMarshallerKind
     {
         /// <summary>

diff --git a/....Private.CoreLib/src/System/Runtime/InteropServices/Marshalling/PointerArrayMarshaller.cs b/....Private.CoreLib/src/System/Runtime/InteropServices/Marshalling/PointerArrayMarshaller.cs
@@ -50,8 +50,8 @@ public PointerArrayMarshaller(T*[]? array, int sizeOfNativeElement)
         /// <remarks>
         /// The <paramref name="buffer"/> must not be movable - that is, it should not be
         /// on the managed heap or it should be pinned.
-        /// <seealso cref="CustomTypeMarshallerFeatures.CallerAllocatedBuffer"/>
         /// </remarks>
+        /// <seealso cref="CustomTypeMarshallerFeatures.CallerAllocatedBuffer"/>
         public PointerArrayMarshaller(T*[]? array, Span<byte> buffer, int sizeOfNativeElement)
         {
             _allocatedMemory = default;
@@ -83,19 +83,15 @@ public PointerArrayMarshaller(T*[]? array, Span<byte> buffer, int sizeOfNativeEl
         /// Gets a span that points to the memory where the managed values of the array are stored.
         /// </summary>
         /// <returns>Span over managed values of the array.</returns>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerDirection.In"/>
-        /// </remarks>
         public ReadOnlySpan<IntPtr> GetManagedValuesSource() => Unsafe.As<IntPtr[]>(_managedArray);
 
         /// <summary>
         /// Gets a span that points to the memory where the unmarshalled managed values of the array should be stored.
         /// </summary>
         /// <param name="length">Length of the array.</param>
         /// <returns>Span where managed values of the array should be stored.</returns>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerDirection.Out"/>
-        /// </remarks>
         public Span<IntPtr> GetManagedValuesDestination(int length)
         {
             if (_allocatedMemory == IntPtr.Zero)
@@ -110,9 +106,7 @@ public Span<IntPtr> GetManagedValuesDestination(int length)
         /// </summary>
         /// <param name="length">Length of the array.</param>
         /// <returns>Span over the native values of the array.</returns>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerDirection.Out"/>
-        /// </remarks>
         public ReadOnlySpan<byte> GetNativeValuesSource(int length)
         {
             if (_allocatedMemory == IntPtr.Zero)
@@ -127,9 +121,7 @@ public ReadOnlySpan<byte> GetNativeValuesSource(int length)
         /// Returns a span that points to the memory where the native values of the array should be stored.
         /// </summary>
         /// <returns>Span where native values of the array should be stored.</returns>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerDirection.In"/>
-        /// </remarks>
         public Span<byte> GetNativeValuesDestination() => _span;
 
         /// <summary>
@@ -140,34 +132,26 @@ public ReadOnlySpan<byte> GetNativeValuesSource(int length)
         /// <summary>
         /// Returns the native value representing the array.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.TwoStageMarshalling"/>
-        /// </remarks>
         public byte* ToNativeValue() => (byte*)Unsafe.AsPointer(ref GetPinnableReference());
 
         /// <summary>
         /// Sets the native value representing the array.
         /// </summary>
         /// <param name="value">The native value.</param>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.TwoStageMarshalling"/>
-        /// </remarks>
         public void FromNativeValue(byte* value) => _allocatedMemory = (IntPtr)value;
 
         /// <summary>
         /// Returns the managed array.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerDirection.Out"/>
-        /// </remarks>
         public T*[]? ToManaged() => _managedArray;
 
         /// <summary>
         /// Frees native resources.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.UnmanagedResources"/>
-        /// </remarks>
         public void FreeNative()
         {
             Marshal.FreeCoTaskMem(_allocatedMemory);

diff --git a/...m.Private.CoreLib/src/System/Runtime/InteropServices/Marshalling/Utf16StringMarshaller.cs b/...m.Private.CoreLib/src/System/Runtime/InteropServices/Marshalling/Utf16StringMarshaller.cs
@@ -31,34 +31,26 @@ public Utf16StringMarshaller(string? str)
         /// <summary>
         /// Returns the native value representing the string.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.TwoStageMarshalling"/>
-        /// </remarks>
         public void* ToNativeValue() => _nativeValue;
 
         /// <summary>
         /// Sets the native value representing the string.
         /// </summary>
         /// <param name="value">The native value.</param>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.TwoStageMarshalling"/>
-        /// </remarks>
         public void FromNativeValue(void* value) => _nativeValue = value;
 
         /// <summary>
         /// Returns the managed string.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerDirection.Out"/>
-        /// </remarks>
         public string? ToManaged() => Marshal.PtrToStringUni((IntPtr)_nativeValue);
 
         /// <summary>
         /// Frees native resources.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.UnmanagedResources"/>
-        /// </remarks>
         public void FreeNative()
         {
             Marshal.FreeCoTaskMem((IntPtr)_nativeValue);

diff --git a/...em.Private.CoreLib/src/System/Runtime/InteropServices/Marshalling/Utf8StringMarshaller.cs b/...em.Private.CoreLib/src/System/Runtime/InteropServices/Marshalling/Utf8StringMarshaller.cs
@@ -33,8 +33,8 @@ public Utf8StringMarshaller(string? str)
         /// <remarks>
         /// The <paramref name="buffer"/> must not be movable - that is, it should not be
         /// on the managed heap or it should be pinned.
-        /// <seealso cref="CustomTypeMarshallerFeatures.CallerAllocatedBuffer"/>
         /// </remarks>
+        /// <seealso cref="CustomTypeMarshallerFeatures.CallerAllocatedBuffer"/>
         public Utf8StringMarshaller(string? str, Span<byte> buffer)
         {
             _allocated = false;
@@ -69,18 +69,14 @@ public Utf8StringMarshaller(string? str, Span<byte> buffer)
         /// <summary>
         /// Returns the native value representing the string.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.TwoStageMarshalling"/>
-        /// </remarks>
         public byte* ToNativeValue() => _nativeValue;
 
         /// <summary>
         /// Sets the native value representing the string.
         /// </summary>
         /// <param name="value">The native value.</param>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.TwoStageMarshalling"/>
-        /// </remarks>
         public void FromNativeValue(byte* value)
         {
             _nativeValue = value;
@@ -90,17 +86,13 @@ public void FromNativeValue(byte* value)
         /// <summary>
         /// Returns the managed string.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerDirection.Out"/>
-        /// </remarks>
         public string? ToManaged() => Marshal.PtrToStringUTF8((IntPtr)_nativeValue);
 
         /// <summary>
         /// Frees native resources.
         /// </summary>
-        /// <remarks>
         /// <seealso cref="CustomTypeMarshallerFeatures.UnmanagedResources"/>
-        /// </remarks>
         public void FreeNative()
         {
             if (_allocated)