math: Improve comments.

[pspp] / src / math / sort.h

diff --git a/src/math/sort.h b/src/math/sort.h
index 1948d0abea10df18edf47fb81cd736922a99fccb..2f1d3899a864aef42a9273cf3588c984df38c558 100644 (file)
--- a/src/math/sort.h
+++ b/src/math/sort.h
@@ -1,5 +1,5 @@
 /* PSPP - a program for statistical analysis.
-   Copyright (C) 1997-9, 2000, 2006 Free Software Foundation, Inc.
+   Copyright (C) 1997-9, 2000, 2006, 2009 Free Software Foundation, Inc.
 
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -17,17 +17,30 @@
 #ifndef MATH_SORT_H
 #define MATH_SORT_H 1
 
-#include <stddef.h>
-#include <stdbool.h>
+/* Support for sorting cases.
+
+   Use sort_create_writer() to sort cases in the most general way:
+
+   - Create a casewriter with sort_create_writer(), specifying the sort
+     criteria.
+   - Write all of the cases to be sorted to the casewriter, e.g. with
+     casewriter_write().
+   - Obtain the sorted results with casewriter_make_reader().
+
+  sort_execute() and sort_execute_1var() are shortcuts for situations where the
+  cases are already available from a casereader.
+
+  All of these functions can efficiently sort data bigger than memory. */
 
 struct subcase;
+struct caseproto;
 struct variable;
 
 extern int min_buffers ;
 extern int max_buffers ;
 
 struct casewriter *sort_create_writer (const struct subcase *,
-                                       size_t value_cnt);
+                                       const struct caseproto *);
 struct casereader *sort_execute (struct casereader *, const struct subcase *);
 struct casereader *sort_execute_1var (struct casereader *,
                                       const struct variable *);