Clarify DataFrame row selection documentation

src/Microsoft.Data.Analysis/DataFrame.cs

@@ -79,44 +79,68 @@ public DataFrame(params DataFrameColumn[] columns)
         }
 
         /// <summary>
-        /// Returns a new DataFrame using the boolean values in <paramref name="filter"/>
+        /// Returns a new <see cref="DataFrame"/> containing the rows selected by <paramref name="filter"/>.
         /// </summary>
-        /// <param name="filter">A column of booleans</param>
+        /// <param name="filter">
+        /// A column whose value at each position selects the row at the same position.
+        /// A value of <see langword="true"/> includes the row; <see langword="false"/> or <see langword="null"/> excludes it.
+        /// If the column is shorter than this <see cref="DataFrame"/>, rows beyond the column's length are excluded.
+        /// </param>
         public DataFrame Filter(PrimitiveDataFrameColumn<bool> filter) => Clone(filter);
 
         /// <summary>
-        /// Returns a new DataFrame using the row indices in <paramref name="rowIndices"/>
+        /// Returns a new <see cref="DataFrame"/> containing the rows specified by <paramref name="rowIndices"/>.
         /// </summary>
-        /// <param name="rowIndices">A column of row indices</param>
+        /// <param name="rowIndices">
+        /// A column whose values are zero-based row indices into this <see cref="DataFrame"/>.
+        /// The values determine the order of the rows in the result, and repeated values produce repeated rows.
+        /// </param>
         public DataFrame Filter(PrimitiveDataFrameColumn<int> rowIndices) => Clone(rowIndices);
 
         /// <summary>
-        /// Returns a new DataFrame using the row indices in <paramref name="rowIndices"/>
+        /// Returns a new <see cref="DataFrame"/> containing the rows specified by <paramref name="rowIndices"/>.
         /// </summary>
-        /// <param name="rowIndices">A column of row indices</param>
+        /// <param name="rowIndices">
+        /// A column whose values are zero-based row indices into this <see cref="DataFrame"/>.
+        /// The values determine the order of the rows in the result, and repeated values produce repeated rows.
+        /// </param>
         public DataFrame Filter(PrimitiveDataFrameColumn<long> rowIndices) => Clone(rowIndices);
 
         /// <summary>
-        /// Returns a new DataFrame using the boolean values in filter
+        /// Returns a new <see cref="DataFrame"/> containing the rows selected by <paramref name="rowFilter"/>.
         /// </summary>
-        /// <param name="rowFilter">A column of booleans</param>
+        /// <param name="rowFilter">
+        /// A column whose value at each position selects the row at the same position.
+        /// A value of <see langword="true"/> includes the row; <see langword="false"/> or <see langword="null"/> excludes it.
+        /// If the column is shorter than this <see cref="DataFrame"/>, rows beyond the column's length are excluded.
+        /// </param>
         public DataFrame this[PrimitiveDataFrameColumn<bool> rowFilter] => Filter(rowFilter);
 
         /// <summary>
-        /// Returns a new DataFrame using the row indices in <paramref name="rowIndices"/>
+        /// Returns a new <see cref="DataFrame"/> containing the rows specified by <paramref name="rowIndices"/>.
         /// </summary>
-        /// <param name="rowIndices">A column of row indices</param>
+        /// <param name="rowIndices">
+        /// A column whose values are zero-based row indices into this <see cref="DataFrame"/>.
+        /// The values determine the order of the rows in the result, and repeated values produce repeated rows.
+        /// </param>
         public DataFrame this[PrimitiveDataFrameColumn<int> rowIndices] => Filter(rowIndices);
 
         /// <summary>
-        /// Returns a new DataFrame using the row indices in <paramref name="rowIndices"/>
+        /// Returns a new <see cref="DataFrame"/> containing the rows specified by <paramref name="rowIndices"/>.
         /// </summary>
-        /// <param name="rowIndices">A column of row indices</param>
+        /// <param name="rowIndices">
+        /// A column whose values are zero-based row indices into this <see cref="DataFrame"/>.
+        /// The values determine the order of the rows in the result, and repeated values produce repeated rows.
+        /// </param>
         public DataFrame this[PrimitiveDataFrameColumn<long> rowIndices] => Filter(rowIndices);
 
         /// <summary>
-        /// Returns a new DataFrame using the row indices in <paramref name="rowIndices"/>
+        /// Returns a new <see cref="DataFrame"/> containing the rows specified by <paramref name="rowIndices"/>.
         /// </summary>
+        /// <param name="rowIndices">
+        /// A collection of zero-based row indices into this <see cref="DataFrame"/>.
+        /// The enumeration order determines the order of the rows in the result, and repeated values produce repeated rows.
+        /// </param>
         public DataFrame this[IEnumerable<int> rowIndices]
         {
             get
@@ -127,8 +151,12 @@ public DataFrame this[IEnumerable<int> rowIndices]
         }
 
         /// <summary>
-        /// Returns a new DataFrame using the row indices in <paramref name="rowIndices"/>
+        /// Returns a new <see cref="DataFrame"/> containing the rows specified by <paramref name="rowIndices"/>.
         /// </summary>
+        /// <param name="rowIndices">
+        /// A collection of zero-based row indices into this <see cref="DataFrame"/>.
+        /// The enumeration order determines the order of the rows in the result, and repeated values produce repeated rows.
+        /// </param>
         public DataFrame this[IEnumerable<long> rowIndices]
         {
             get
@@ -139,8 +167,13 @@ public DataFrame this[IEnumerable<long> rowIndices]
         }
 
         /// <summary>
-        /// Returns a new DataFrame using the boolean values in <paramref name="rowFilter"/>
+        /// Returns a new <see cref="DataFrame"/> containing the rows selected by <paramref name="rowFilter"/>.
         /// </summary>
+        /// <param name="rowFilter">
+        /// A collection whose value at each position selects the row at the same position.
+        /// A value of <see langword="true"/> includes the row and <see langword="false"/> excludes it.
+        /// If the collection contains fewer values than this <see cref="DataFrame"/> has rows, the remaining rows are excluded.
+        /// </param>
         public DataFrame this[IEnumerable<bool> rowFilter]
         {
             get

src/Microsoft.Data.Analysis/DataFrameColumn.Computations.cs

@@ -47,6 +47,12 @@ public virtual DataFrameColumn CumulativeMax(bool inPlace = false)
         /// <summary>
         /// Updates column values at rowIndices with its cumulative rowIndices maximum
         /// </summary>
+        /// <param name="rowIndices">
+        /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly.
+        /// </param>
+        /// <param name="inPlace">
+        /// <see langword="true"/> to update this column; <see langword="false"/> to return a new column.
+        /// </param>
         public virtual DataFrameColumn CumulativeMax(IEnumerable<long> rowIndices, bool inPlace = false)
         {
             throw new NotImplementedException();
@@ -63,6 +69,12 @@ public virtual DataFrameColumn CumulativeMin(bool inPlace = false)
         /// <summary>
         /// Updates column values at rowIndices with its cumulative rowIndices minimum
         /// </summary>
+        /// <param name="rowIndices">
+        /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly.
+        /// </param>
+        /// <param name="inPlace">
+        /// <see langword="true"/> to update this column; <see langword="false"/> to return a new column.
+        /// </param>
         public virtual DataFrameColumn CumulativeMin(IEnumerable<long> rowIndices, bool inPlace = false)
         {
             throw new NotImplementedException();
@@ -79,6 +91,12 @@ public virtual DataFrameColumn CumulativeProduct(bool inPlace = false)
         /// <summary>
         /// Updates column values at rowIndices with its cumulative rowIndices product
         /// </summary>
+        /// <param name="rowIndices">
+        /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly.
+        /// </param>
+        /// <param name="inPlace">
+        /// <see langword="true"/> to update this column; <see langword="false"/> to return a new column.
+        /// </param>
         public virtual DataFrameColumn CumulativeProduct(IEnumerable<long> rowIndices, bool inPlace = false)
         {
             throw new NotImplementedException();
@@ -95,6 +113,12 @@ public virtual DataFrameColumn CumulativeSum(bool inPlace = false)
         /// <summary>
         /// Updates column values at rowIndices with its cumulative rowIndices sum
         /// </summary>
+        /// <param name="rowIndices">
+        /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly.
+        /// </param>
+        /// <param name="inPlace">
+        /// <see langword="true"/> to update this column; <see langword="false"/> to return a new column.
+        /// </param>
         public virtual DataFrameColumn CumulativeSum(IEnumerable<long> rowIndices, bool inPlace = false)
         {
             throw new NotImplementedException();
@@ -111,6 +135,9 @@ public virtual object Max()
         /// <summary>
         /// Returns the maximum of the values at rowIndices
         /// </summary>
+        /// <param name="rowIndices">
+        /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly.
+        /// </param>
         public virtual object Max(IEnumerable<long> rowIndices)
         {
             throw new NotImplementedException();
@@ -127,6 +154,9 @@ public virtual object Min()
         /// <summary>
         /// Returns the minimum of the values at the rowIndices
         /// </summary>
+        /// <param name="rowIndices">
+        /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly.
+        /// </param>
         public virtual object Min(IEnumerable<long> rowIndices)
         {
             throw new NotImplementedException();
@@ -143,6 +173,9 @@ public virtual object Product()
         /// <summary>
         /// Returns the product of the values at the rowIndices
         /// </summary>
+        /// <param name="rowIndices">
+        /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly.
+        /// </param>
         public virtual object Product(IEnumerable<long> rowIndices)
         {
             throw new NotImplementedException();
@@ -159,6 +192,9 @@ public virtual object Sum()
         /// <summary>
         /// Returns the sum of the values at the rowIndices
         /// </summary>
+        /// <param name="rowIndices">
+        /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly.
+        /// </param>
         public virtual object Sum(IEnumerable<long> rowIndices)
         {
             throw new NotImplementedException();

src/Microsoft.Data.Analysis/DataFrameColumn.Computations.tt

@@ -22,6 +22,16 @@ namespace Microsoft.Data.Analysis
         /// <summary>
         /// <#=compMethod.MethodComments#>
         /// </summary>
+<# if (compMethod.SupportsRowSubsets == true) {#>
+        /// <param name="rowIndices">
+        /// The zero-based indices of rows to process, in enumeration order. Repeated indices are processed repeatedly.
+        /// </param>
+<# } #>
+<# if (compMethod.MethodType == MethodType.ElementwiseComputation && compMethod.HasReturnValue == false && compMethod.SupportsRowSubsets == true) {#>
+        /// <param name="inPlace">
+        /// <see langword="true"/> to update this column; <see langword="false"/> to return a new column.
+        /// </param>
+<# } #>
 <# if (compMethod.MethodType == MethodType.ElementwiseComputation && compMethod.HasReturnValue == false && compMethod.SupportsRowSubsets == true) {#>
         public virtual DataFrameColumn <#=compMethod.MethodName#>(IEnumerable<long> rowIndices, bool inPlace = false)
 <# } else if (compMethod.MethodType == MethodType.ElementwiseComputation && compMethod.HasReturnValue == false) {#>

src/Microsoft.Data.Analysis/DataFrameColumn.cs

@@ -210,18 +210,26 @@ public object this[long rowIndex]
         protected internal virtual void Resize(long length) => throw new NotImplementedException();
 
         /// <summary>
-        /// Clone column to produce a copy
+        /// Clones the column.
         /// </summary>
-        /// <param name="numberOfNullsToAppend"></param>
+        /// <param name="numberOfNullsToAppend">The number of null values to append to the copied values.</param>
         /// <returns>A new <see cref="DataFrameColumn"/></returns>
         public DataFrameColumn Clone(long numberOfNullsToAppend = 0) => CloneImplementation(numberOfNullsToAppend);
 
         /// <summary>
-        /// Clone column to produce a copy potentially changing the order of values by supplying mapIndices and an invert flag
+        /// Clones the column, selecting and ordering values according to <paramref name="mapIndices"/>.
         /// </summary>
-        /// <param name="mapIndices"></param>
-        /// <param name="invertMapIndices"></param>
-        /// <param name="numberOfNullsToAppend"></param>
+        /// <param name="mapIndices">
+        /// A Boolean, <see cref="int"/>, or <see cref="long"/> column that determines which values to copy.
+        /// For a Boolean column, the value at each position selects the value at the same position when it is
+        /// <see langword="true"/>. For an integer column, each value is a zero-based index into this column;
+        /// the map order determines the result order, and repeated indices produce repeated values.
+        /// </param>
+        /// <param name="invertMapIndices">
+        /// <see langword="true"/> to process integer values in <paramref name="mapIndices"/> in reverse order;
+        /// otherwise, <see langword="false"/>. This parameter does not affect a Boolean map.
+        /// </param>
+        /// <param name="numberOfNullsToAppend">The number of null values to append after the selected values.</param>
         /// <returns>A new <see cref="DataFrameColumn"/></returns>
         public DataFrameColumn Clone(DataFrameColumn mapIndices, bool invertMapIndices = false, long numberOfNullsToAppend = 0) => CloneImplementation(mapIndices, invertMapIndices, numberOfNullsToAppend);
 

src/Microsoft.Data.Analysis/DataFrameColumns/ArrowStringDataFrameColumn.cs

@@ -365,11 +365,13 @@ protected internal override Apache.Arrow.Array ToArrowArray(long startIndex, int
 
         protected internal override PrimitiveDataFrameColumn<long> GetSortIndices(bool ascending, bool putNullValuesLast) => throw new NotSupportedException();
 
+        /// <inheritdoc cref="DataFrameColumn.Clone(long)"/>
         public new ArrowStringDataFrameColumn Clone(long numberOfNullsToAppend = 0)
         {
             return (ArrowStringDataFrameColumn)CloneImplementation(numberOfNullsToAppend);
         }
 
+        /// <inheritdoc cref="DataFrameColumn.Clone(DataFrameColumn, bool, long)"/>
         public new ArrowStringDataFrameColumn Clone(DataFrameColumn mapIndices, bool invertMapIndices = false, long numberOfNullsToAppend = 0)
         {
             return (ArrowStringDataFrameColumn)CloneImplementation(mapIndices, invertMapIndices, numberOfNullsToAppend);

src/Microsoft.Data.Analysis/DataFrameColumns/StringDataFrameColumn.cs

@@ -275,11 +275,13 @@ ValueTuple<string, int> GetFirstNonNullValueStartingAtIndex(int stringBufferInde
             return columnSortIndices;
         }
 
+        /// <inheritdoc cref="DataFrameColumn.Clone(DataFrameColumn, bool, long)"/>
         public new StringDataFrameColumn Clone(DataFrameColumn mapIndices, bool invertMapIndices, long numberOfNullsToAppend)
         {
             return (StringDataFrameColumn)CloneImplementation(mapIndices, invertMapIndices, numberOfNullsToAppend);
         }
 
+        /// <inheritdoc cref="DataFrameColumn.Clone(long)"/>
         public new StringDataFrameColumn Clone(long numberOfNullsToAppend = 0)
         {
             return (StringDataFrameColumn)CloneImplementation(numberOfNullsToAppend);

src/Microsoft.Data.Analysis/DataFrameColumns/VBufferDataFrameColumn.cs

@@ -267,11 +267,13 @@ private VBufferDataFrameColumn<T> CloneImplementation(PrimitiveDataFrameColumn<i
             return ret;
         }
 
+        /// <inheritdoc cref="DataFrameColumn.Clone(DataFrameColumn, bool, long)"/>
         public new VBufferDataFrameColumn<T> Clone(DataFrameColumn mapIndices, bool invertMapIndices, long numberOfNullsToAppend)
         {
             return (VBufferDataFrameColumn<T>)CloneImplementation(mapIndices, invertMapIndices, numberOfNullsToAppend);
         }
 
+        /// <inheritdoc cref="DataFrameColumn.Clone(long)"/>
         public new VBufferDataFrameColumn<T> Clone(long numberOfNullsToAppend = 0)
         {
             return (VBufferDataFrameColumn<T>)CloneImplementation(numberOfNullsToAppend);