Clarify documentation for make_unit_whatsit

1 files changed, 11 insertions, 8 deletions

diff --git a/unit_label.c b/unit_label.c
index b050b89..b53e4a3 100644
--- a/unit_label.c
+++ b/unit_label.c
@@ -7,15 +7,18 @@
  * label. While the value is larger than the current unit's maximum count,
  * the value is divided by this count and the next unit in the table is
  * examined. Example:
- *    100 flooby
- *    500 glargle
- *     30 lafplop     // Can be any count
- *       0 NULL       // Can be any count
+ *    {100, "flooby" },
+ *    {500, "glargle"},
+ *    { 30, "lafplop"},  // Can be any non-zero count
+ *    {  0, NULL     }   // Can be any count
  *
- * Given this table, a value of:
- *    150 will store glargle and return 1.5
- *     50 will store flooby  and return 50
- *  55000 will store lafplop and return 1.1
+ * Given this table is in `labels`,
+ *  ret1 = make_unit_whatsit(labels, &unit1, 150);
+ *  ret2 = make_unit_whatsit(labels, &unit2, 50);
+ *  ret3 = make_unit_whatsit(labels, &unit3, 55000);
+ * leaves ret1 as 1.5 and unit1 as "gargle",
+ * leaves ret2 as 50  and unit2 as "flooby",
+ * leaves ret3 as 1.1 and unit3 as "lafplop",
  */
 double make_unit_whatsit(const struct unit_label l[], char **unit, double value) {
 	size_t i = 0;