common: fix up BOLT 1 references.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

common/ping.c

@@ -15,23 +15,29 @@ bool check_ping_make_pong(const tal_t *ctx, const u8 *ping, u8 **pong)
 	/* FIXME: */
 	/* BOLT #1:
 	 *
-	 * A node receiving a `ping` message SHOULD fail the channels if it
+	 * A node receiving a `ping` message:
-	 * has received significantly in excess of one `ping` per 30 seconds,
+	 *  - SHOULD fail the channels if it has received significantly in
+	 *    excess of one `ping` per 30 seconds.
 	 */
 
 	/* BOLT #1:
 	 *
-	 * ... otherwise if `num_pong_bytes` is less than 65532 it MUST
+	 * A node receiving a `ping` message:
-	 * respond by sending a `pong` message with `byteslen` equal to
+	 *...
-	 * `num_pong_bytes`, otherwise it MUST ignore the `ping`.
+	 *  - if `num_pong_bytes` is less than 65532:
+	 *    - MUST respond by sending a `pong` message, with `byteslen` equal
+	 *      to `num_pong_bytes`.
+	 *  - otherwise (`num_pong_bytes` is **not** less than 65532):
+	 *    - MUST ignore the `ping`.
 	 */
 	if (num_pong_bytes < 65532) {
 		/* BOLT #1:
 		 *
-		 * A node sending `pong` or `ping` SHOULD set `ignored` to
+		 * A node sending a `pong` message:
-		 * zeroes, but MUST NOT set `ignored` to sensitive data such
+		 *   - SHOULD set `ignored` to 0s.
-		 * as secrets, or portions of initialized memory.
+		 *   - MUST NOT set `ignored` to sensitive data such as secrets
-		*/
+		 *     or portions of initialized memory.
+		 */
 		ignored = tal_arrz(ctx, u8, num_pong_bytes);
 #if DEVELOPER
 		/* Embed version */
@@ -49,9 +55,10 @@ u8 *make_ping(const tal_t *ctx, u16 num_pong_bytes, u16 padlen)
 {
 	/* BOLT #1:
 	 *
-	 * A node sending `pong` or `ping` SHOULD set `ignored` to zeroes, but
+	 * A node sending a `ping` message:
-	 * MUST NOT set `ignored` to sensitive data such as secrets, or
+	 *  - SHOULD set `ignored` to 0s.
-	 * portions of initialized memory.
+	 *  - MUST NOT set `ignored` to sensitive data such as secrets or
+	 *    portions of initialized memory.
 	 */
 	u8 *ping, *ignored = tal_arrz(ctx, u8, padlen);
 

common/wire_error.c

@@ -12,8 +12,8 @@ u8 *towire_errorfmtv(const tal_t *ctx,
 {
 	/* BOLT #1:
 	 *
-	 * The channel is referred to by `channel_id` unless `channel_id` is
+	 * The channel is referred to by `channel_id`, unless `channel_id` is
-	 * zero (ie. all bytes zero), in which case it refers to all
+	 * 0 (i.e. all bytes are 0), in which case it refers to all
 	 * channels. */
 	static const struct channel_id all_channels;
 	char *estr;
@@ -63,10 +63,12 @@ char *sanitize_error(const tal_t *ctx, const u8 *errmsg,
 
 	/* BOLT #1:
 	 *
-	 * A receiving node SHOULD only print out `data` verbatim if the
+	 * The receiving node:
-	 * string is composed solely of printable ASCII characters.  For
+	 *...
-	 * reference, the printable character set includes byte values 32
+	 *  - if `data` is not composed solely of printable ASCII characters
-	 * through 127 inclusive.
+	 *   (For reference: the printable character set includes byte values 32
+	 *   through 126, inclusive):
+	 *    - SHOULD NOT print out `data` verbatim.
 	 */
 	for (i = 0; i < tal_len(data); i++) {
 		if (data[i] < 32 || data[i] > 127) {

common/wire_error.h

@@ -34,9 +34,8 @@ u8 *towire_errorfmtv(const tal_t *ctx,
 
 /* BOLT #1:
  *
- * A node receiving `error` MUST fail the channel referred to by the message,
+ * The channel is referred to by `channel_id`, unless `channel_id` is 0
- * or if `channel_id` is zero, it MUST fail all channels and MUST close the
+ * (i.e. all bytes are 0), in which case it refers to all channels.
- * connection.
  */
 /**
  * channel_id_is_all - True if channel_id is all zeroes.

common/wireaddr.h

@@ -18,7 +18,7 @@ struct sockaddr_un;
 /* BOLT #1:
  *
  * The default TCP port is 9735. This corresponds to hexadecimal
- * `0x2607`, the Unicode code point for LIGHTNING.
+ * `0x2607`: the Unicode code point for LIGHTNING.
  */
 #define DEFAULT_PORT 9735