bkietz commented on a change in pull request #9130:
URL: https://github.com/apache/arrow/pull/9130#discussion_r555177802
##########
File path: cpp/src/arrow/dataset/partition.h
##########
@@ -288,16 +288,58 @@ class ARROW_DS_EXPORT PartitioningOrFactory {
/// \brief Assemble lists of indices of identical rows.
///
/// \param[in] by A StructArray whose columns will be used as grouping
criteria.
-/// \return A StructArray mapping unique rows (in field "values", represented
as a
-/// StructArray with the same fields as `by`) to lists of indices where
-/// that row appears (in field "groupings").
+/// Top level nulls are invalid, as are empty criteria (no
grouping
+/// columns).
+/// \return A array of type `struct<values: by.type, groupings: list<int64>>`,
+/// which is a mapping from unique rows (field "values") to lists of
+/// indices into `by` where that row appears (field "groupings").
+///
+/// For example,
+/// MakeGroupings([
+/// {"a": "ex", "b": 0},
+/// {"a": "ex", "b": 0},
+/// {"a": "why", "b": 0},
+/// {"a": "why", "b": 0},
+/// {"a": "ex", "b": 0},
+/// {"a": "why", "b": 1}
+/// ]) == [
+/// {"values": {"a": "ex", "b": 0}, "groupings": [0, 1, 4]},
+/// {"values": {"a": "why", "b": 0}, "groupings": [2, 3]},
+/// {"values": {"a": "why", "b": 1}, "groupings": [5]}
+/// ]
ARROW_DS_EXPORT
Result<std::shared_ptr<StructArray>> MakeGroupings(const StructArray& by);
-/// \brief Produce slices of an Array which correspond to the provided
groupings.
+/// \brief Produce a ListArray whose slots are slices of `array` which
correspond to the
Review comment:
I'll use "selections" instead
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
