param: updated comments in the spirit of #1899

Signed-off-by: Mark Beckwith <wythe@intrig.com>

lightningd/param.h

@@ -2,26 +2,33 @@
 #define LIGHTNING_LIGHTNINGD_PARAM_H
 #include "config.h"
 
-/*
+/*~ Greetings adventurer!
-  Typesafe callback system for unmarshalling and validating json parameters.
+ *
-
+ * Do you want to automatically validate json input and unmarshall it into
-  Typical usage:
+ * local variables, all using typesafe callbacks?  And on error,
-	unsigned *cltv;
+ * call command_fail with a proper error message? Then you've come to the
-	u64 *msatoshi;
+ * right place!
-	const jsmntok_t *note;
+ *
-	u64 *expiry;
+ * Here is a simple example of using the system:
-
+ *
-	if (!param(cmd, buffer, params,
+ * 	unsigned *cltv;
-		   p_req("cltv", json_tok_number, &cltv),
+ * 	u64 *msatoshi;
-		   p_opt("msatoshi", json_tok_u64, &msatoshi),
+ * 	const jsmntok_t *note;
-		   p_opt_tok("note", &note),
+ * 	u64 *expiry;
-		   p_opt_def("expiry", json_tok_u64, &expiry, 3600),
+ *
-		   NULL))
+ * 	if (!param(cmd, buffer, params,
-		return;
+ * 		   p_req("cltv", json_tok_number, &cltv),
-
+ * 		   p_opt("msatoshi", json_tok_u64, &msatoshi),
-  See json_invoice() for a good example.  The common callbacks can be found in
+ * 		   p_opt("note", json_tok_tok, &note),
-  lightningd/json.c.  Use them as an example for writing your own custom
+ * 		   p_opt_def("expiry", json_tok_u64, &expiry, 3600),
-  callbacks.
+ * 		   NULL))
+ * 		return;
+ *
+ * If param() returns true then you're good to go.
+ *
+ * All the command handlers throughout the code use this system.
+ * json_invoice() is a great example.  The common callbacks can be found in
+ * lightningd/json.c.  Use them directly or feel free to write your own.
  */
 
 /*