Backport docs for System.Numerics.Vectors

src/libraries/System.Numerics.Vectors/src/System.Numerics.Vectors.csproj

@@ -3,8 +3,9 @@
     <IsPartialFacadeAssembly>true</IsPartialFacadeAssembly>
     <TargetFrameworks>$(NetCoreAppCurrent)</TargetFrameworks>
     <Nullable>enable</Nullable>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
   <ItemGroup>
     <ProjectReference Include="$(CoreLibProject)" />
   </ItemGroup>
-</Project>
+</Project>

src/libraries/System.Private.CoreLib/src/System/Numerics/Plane.cs

@@ -7,52 +7,54 @@
 
 namespace System.Numerics
 {
-    /// <summary>A structure encapsulating a 3D Plane</summary>
+    /// <summary>Represents a plane in three-dimensional space.</summary>
+    /// <remarks><format type="text/markdown"><![CDATA[
+    /// [!INCLUDE[vectors-are-rows-paragraph](~/includes/system-numerics-vectors-are-rows.md)]
+    /// ]]></format></remarks>
     [Intrinsic]
     public struct Plane : IEquatable<Plane>
     {
         private const float NormalizeEpsilon = 1.192092896e-07f; // smallest such that 1.0+NormalizeEpsilon != 1.0
 
-        /// <summary>The normal vector of the Plane.</summary>
+        /// <summary>The normal vector of the plane.</summary>
         public Vector3 Normal;
 
-        /// <summary>The distance of the Plane along its normal from the origin.</summary>
+        /// <summary>The distance of the plane along its normal from the origin.</summary>
         public float D;
 
-        /// <summary>Constructs a Plane from the X, Y, and Z components of its normal, and its distance from the origin on that normal.</summary>
-        /// <param name="x">The X-component of the normal.</param>
-        /// <param name="y">The Y-component of the normal.</param>
-        /// <param name="z">The Z-component of the normal.</param>
-        /// <param name="d">The distance of the Plane along its normal from the origin.</param>
+        /// <summary>Creates a <see cref="System.Numerics.Plane" /> object from the X, Y, and Z components of its normal, and its distance from the origin on that normal.</summary>
+        /// <param name="x">The X component of the normal.</param>
+        /// <param name="y">The Y component of the normal.</param>
+        /// <param name="z">The Z component of the normal.</param>
+        /// <param name="d">The distance of the plane along its normal from the origin.</param>
         public Plane(float x, float y, float z, float d)
         {
             Normal = new Vector3(x, y, z);
             D = d;
         }
 
-        /// <summary>Constructs a Plane from the given normal and distance along the normal from the origin.</summary>
-        /// <param name="normal">The Plane's normal vector.</param>
-        /// <param name="d">The Plane's distance from the origin along its normal vector.</param>
+        /// <summary>Creates a <see cref="System.Numerics.Plane" /> object from a specified normal and the distance along the normal from the origin.</summary>
+        /// <param name="normal">The plane's normal vector.</param>
+        /// <param name="d">The plane's distance from the origin along its normal vector.</param>
         public Plane(Vector3 normal, float d)
         {
             Normal = normal;
             D = d;
         }
 
-        /// <summary>Constructs a Plane from the given Vector4.</summary>
-        /// <param name="value">A vector whose first 3 elements describe the normal vector,
-        /// and whose W component defines the distance along that normal from the origin.</param>
+        /// <summary>Creates a <see cref="System.Numerics.Plane" /> object from a specified four-dimensional vector.</summary>
+        /// <param name="value">A vector whose first three elements describe the normal vector, and whose <see cref="System.Numerics.Vector4.W" /> defines the distance along that normal from the origin.</param>
         public Plane(Vector4 value)
         {
             Normal = new Vector3(value.X, value.Y, value.Z);
             D = value.W;
         }
 
-        /// <summary>Creates a Plane that contains the three given points.</summary>
-        /// <param name="point1">The first point defining the Plane.</param>
-        /// <param name="point2">The second point defining the Plane.</param>
-        /// <param name="point3">The third point defining the Plane.</param>
-        /// <returns>The Plane containing the three points.</returns>
+        /// <summary>Creates a <see cref="System.Numerics.Plane" /> object that contains three specified points.</summary>
+        /// <param name="point1">The first point defining the plane.</param>
+        /// <param name="point2">The second point defining the plane.</param>
+        /// <param name="point3">The third point defining the plane.</param>
+        /// <returns>The plane containing the three points.</returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static Plane CreateFromVertices(Vector3 point1, Vector3 point2, Vector3 point3)
         {
@@ -100,9 +102,9 @@ public static Plane CreateFromVertices(Vector3 point1, Vector3 point2, Vector3 p
             }
         }
 
-        /// <summary>Calculates the dot product of a Plane and Vector4.</summary>
-        /// <param name="plane">The Plane.</param>
-        /// <param name="value">The Vector4.</param>
+        /// <summary>Calculates the dot product of a plane and a 4-dimensional vector.</summary>
+        /// <param name="plane">The plane.</param>
+        /// <param name="value">The four-dimensional vector.</param>
         /// <returns>The dot product.</returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static float Dot(Plane plane, Vector4 value)
@@ -113,10 +115,10 @@ public static float Dot(Plane plane, Vector4 value)
                    plane.D * value.W;
         }
 
-        /// <summary>Returns the dot product of a specified Vector3 and the normal vector of this Plane plus the distance (D) value of the Plane.</summary>
+        /// <summary>Returns the dot product of a specified three-dimensional vector and the normal vector of this plane plus the distance (<see cref="System.Numerics.Plane.D" />) value of the plane.</summary>
         /// <param name="plane">The plane.</param>
-        /// <param name="value">The Vector3.</param>
-        /// <returns>The resulting value.</returns>
+        /// <param name="value">The 3-dimensional vector.</param>
+        /// <returns>The dot product.</returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static float DotCoordinate(Plane plane, Vector3 value)
         {
@@ -133,10 +135,10 @@ public static float DotCoordinate(Plane plane, Vector3 value)
             }
         }
 
-        /// <summary>Returns the dot product of a specified Vector3 and the Normal vector of this Plane.</summary>
+        /// <summary>Returns the dot product of a specified three-dimensional vector and the <see cref="System.Numerics.Plane.Normal" /> vector of this plane.</summary>
         /// <param name="plane">The plane.</param>
-        /// <param name="value">The Vector3.</param>
-        /// <returns>The resulting dot product.</returns>
+        /// <param name="value">The three-dimensional vector.</param>
+        /// <returns>The dot product.</returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static float DotNormal(Plane plane, Vector3 value)
         {
@@ -152,9 +154,9 @@ public static float DotNormal(Plane plane, Vector3 value)
             }
         }
 
-        /// <summary>Creates a new Plane whose normal vector is the source Plane's normal vector normalized.</summary>
-        /// <param name="value">The source Plane.</param>
-        /// <returns>The normalized Plane.</returns>
+        /// <summary>Creates a new <see cref="System.Numerics.Plane" /> object whose normal vector is the source plane's normal vector normalized.</summary>
+        /// <param name="value">The source plane.</param>
+        /// <returns>The normalized plane.</returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static Plane Normalize(Plane value)
         {
@@ -190,11 +192,11 @@ public static Plane Normalize(Plane value)
             }
         }
 
-        /// <summary>Transforms a normalized Plane by a Matrix.</summary>
-        /// <param name="plane"> The normalized Plane to transform.
-        /// This Plane must already be normalized, so that its Normal vector is of unit length, before this method is called.</param>
-        /// <param name="matrix">The transformation matrix to apply to the Plane.</param>
-        /// <returns>The transformed Plane.</returns>
+        /// <summary>Transforms a normalized plane by a 4x4 matrix.</summary>
+        /// <param name="plane">The normalized plane to transform.</param>
+        /// <param name="matrix">The transformation matrix to apply to <paramref name="plane" />.</param>
+        /// <returns>The transformed plane.</returns>
+        /// <remarks><paramref name="plane" /> must already be normalized so that its <see cref="System.Numerics.Plane.Normal" /> vector is of unit length before this method is called.</remarks>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static Plane Transform(Plane plane, Matrix4x4 matrix)
         {
@@ -209,11 +211,11 @@ public static Plane Transform(Plane plane, Matrix4x4 matrix)
                 x * m.M41 + y * m.M42 + z * m.M43 + w * m.M44);
         }
 
-        /// <summary> Transforms a normalized Plane by a Quaternion rotation.</summary>
-        /// <param name="plane"> The normalized Plane to transform.
-        /// This Plane must already be normalized, so that its Normal vector is of unit length, before this method is called.</param>
-        /// <param name="rotation">The Quaternion rotation to apply to the Plane.</param>
-        /// <returns>A new Plane that results from applying the rotation.</returns>
+        /// <summary>Transforms a normalized plane by a Quaternion rotation.</summary>
+        /// <param name="plane">The normalized plane to transform.</param>
+        /// <param name="rotation">The Quaternion rotation to apply to the plane.</param>
+        /// <returns>A new plane that results from applying the Quaternion rotation.</returns>
+        /// <remarks><paramref name="plane" /> must already be normalized so that its <see cref="System.Numerics.Plane.Normal" /> vector is of unit length before this method is called.</remarks>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static Plane Transform(Plane plane, Quaternion rotation)
         {
@@ -253,10 +255,12 @@ public static Plane Transform(Plane plane, Quaternion rotation)
                 plane.D);
         }
 
-        /// <summary>Returns a boolean indicating whether the two given Planes are equal.</summary>
-        /// <param name="value1">The first Plane to compare.</param>
-        /// <param name="value2">The second Plane to compare.</param>
-        /// <returns>True if the Planes are equal; False otherwise.</returns>
+        /// <summary>Returns a value that indicates whether two planes are equal.</summary>
+        /// <param name="value1">The first plane to compare.</param>
+        /// <param name="value2">The second plane to compare.</param>
+        /// <returns><see langword="true" /> if <paramref name="value1" /> and <paramref name="value2" /> are equal; otherwise, <see langword="false" />.</returns>
+        /// <remarks>Two <see cref="System.Numerics.Plane" /> objects are equal if their <see cref="System.Numerics.Plane.Normal" /> and <see cref="System.Numerics.Plane.D" /> fields are equal.
+        /// The <see cref="System.Numerics.Plane.op_Equality" /> method defines the operation of the equality operator for <see cref="System.Numerics.Plane" /> objects.</remarks>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static bool operator ==(Plane value1, Plane value2)
         {
@@ -266,28 +270,31 @@ public static Plane Transform(Plane plane, Quaternion rotation)
                     value1.D == value2.D);
         }
 
-        /// <summary>Returns a boolean indicating whether the two given Planes are not equal.</summary>
-        /// <param name="value1">The first Plane to compare.</param>
-        /// <param name="value2">The second Plane to compare.</param>
-        /// <returns>True if the Planes are not equal; False if they are equal.</returns>
+        /// <summary>Returns a value that indicates whether two planes are not equal.</summary>
+        /// <param name="value1">The first plane to compare.</param>
+        /// <param name="value2">The second plane to compare.</param>
+        /// <returns><see langword="true" /> if <paramref name="value1" /> and <paramref name="value2" /> are not equal; otherwise, <see langword="false" />.</returns>
+        /// <remarks>The <see cref="System.Numerics.Plane.op_Inequality" /> method defines the operation of the inequality operator for <see cref="System.Numerics.Plane" /> objects.</remarks>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static bool operator !=(Plane value1, Plane value2)
         {
             return !(value1 == value2);
         }
 
-        /// <summary>Returns a boolean indicating whether the given Object is equal to this Plane instance.</summary>
-        /// <param name="obj">The Object to compare against.</param>
-        /// <returns>True if the Object is equal to this Plane; False otherwise.</returns>
+        /// <summary>Returns a value that indicates whether this instance and a specified object are equal.</summary>
+        /// <param name="obj">The object to compare with the current instance.</param>
+        /// <returns><see langword="true" /> if the current instance and <paramref name="obj" /> are equal; otherwise, <see langword="false" />. If <paramref name="obj" /> is <see langword="null" />, the method returns <see langword="false" />.</returns>
+        /// <remarks>The current instance and <paramref name="obj" /> are equal if <paramref name="obj" /> is a <see cref="System.Numerics.Plane" /> object and their <see cref="System.Numerics.Plane.Normal" /> and <see cref="System.Numerics.Plane.D" /> fields are equal.</remarks>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public override readonly bool Equals([NotNullWhen(true)] object? obj)
         {
             return (obj is Plane other) && Equals(other);
         }
 
-        /// <summary>Returns a boolean indicating whether the given Plane is equal to this Plane instance.</summary>
-        /// <param name="other">The Plane to compare this instance to.</param>
-        /// <returns>True if the other Plane is equal to this instance; False otherwise.</returns>
+        /// <summary>Returns a value that indicates whether this instance and another plane object are equal.</summary>
+        /// <param name="other">The other plane.</param>
+        /// <returns><see langword="true" /> if the two planes are equal; otherwise, <see langword="false" />.</returns>
+        /// <remarks>Two <see cref="System.Numerics.Plane" /> objects are equal if their <see cref="System.Numerics.Plane.Normal" /> and <see cref="System.Numerics.Plane.D" /> fields are equal.</remarks>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public readonly bool Equals(Plane other)
         {
@@ -311,8 +318,9 @@ public override readonly int GetHashCode()
             return Normal.GetHashCode() + D.GetHashCode();
         }
 
-        /// <summary>Returns a String representing this Plane instance.</summary>
-        /// <returns>The string representation.</returns>
+        /// <summary>Returns the string representation of this plane object.</summary>
+        /// <returns>A string that represents this <see cref="System.Numerics.Plane" /> object.</returns>
+        /// <remarks>The string representation of a <see cref="System.Numerics.Plane" /> object use the formatting conventions of the current culture to format the numeric values in the returned string. For example, a <see cref="System.Numerics.Plane" /> object whose string representation is formatted by using the conventions of the en-US culture might appear as <c>{Normal:&lt;1.1, 2.2, 3.3&gt; D:4.4}</c>.</remarks>
         public override readonly string ToString()
         {
             CultureInfo ci = CultureInfo.CurrentCulture;