- This data structure supplies infrastructure for higher-level statistics that
- rely on order statistics. It is a kind of "abstract base class" that is not
- useful on its own. The common pattern for using the statistics based on it
+ The kth order statistic of a statistical sample is equal to its kth-smallest
+ value. The minimum is the first order statistic and the maximum is the
+ largest. This code and data structure supplies infrastructure for
+ higher-level statistics that rely on order statistics. It is a kind of
+ "abstract base class" that is not useful on its own.
+
+ This is implemented here as a kind of "partial frequency table". The
+ order_stats_accumulate() and order_stats_accumulate_idx() functions
+ effectively generate all of the frequency table entries for the variable,
+ one by one, and pass them to the "accumulate" function, if any. They can
+ also record pairs of frequency tables entries surrounding desired target
+ cumulative weights in 'k' data structures.
+
+ Client use
+ ==========
+
+ The common pattern for clients to use statistics based on order statistics