ElementsProject · rustyrussell · Jun 25, 2021 · Jun 16, 2021 · Jun 16, 2021 · Jun 16, 2021
@@ -232,6 +232,12 @@ def is_u16(checker, instance):
             return False
         return instance >= 0 and instance < 2**16
 
+    def is_u8(checker, instance):
+        """8-bit integer"""
+        if not checker.is_type(instance, "integer"):
+            return False
+        return instance >= 0 and instance < 2**8
+
     def is_short_channel_id(checker, instance):
         """Short channel id"""
         if not checker.is_type(instance, "string"):
@@ -307,6 +313,7 @@ def is_txid(checker, instance):
         "u64": is_u64,
         "u32": is_u32,
         "u16": is_u16,
+        "u8": is_u8,
         "pubkey": is_pubkey,
         "msat": is_msat,
         "txid": is_txid,

diff --git a/doc/Makefile b/doc/Makefile
@@ -137,10 +137,15 @@ clean: doc-clean
 check: check-manpages
 
 # This needs plugins, too.
-check-manpages: all-programs
+check-manpages: all-programs check-config-docs
 	@tools/check-manpage.sh cli/lightning-cli doc/lightning-cli.1.md
 	@tools/check-manpage.sh "lightningd/lightningd --lightning-dir=/tmp/" doc/lightningd-config.5.md
 
+# Makes sure that fields mentioned in schema are in man page, and vice versa.
+check-config-docs:
+	@for c in `sed -n 's/^	"\(.*\)": {/\1/p' doc/schemas/listconfigs.schema.json | grep -v '^# version$$' | grep -v '^plugins$$' | grep -v '^important-plugins$$'`; do if ! grep -q "^ \*\*$$c\*\*" doc/lightningd-config.5.md; then echo "$$c undocumented!"; exit 1; fi; done
+	@for c in `grep -v '\[plugin ' doc/lightningd-config.5.md | sed -n 's/^ \*\*\([^*]*\)\*\*.*/\1/p' | grep -v '^\(help\|version\|mainnet\|testnet\|signet\|plugin\|important-plugin\|plugin-dir\|clear-plugins\)$$'`; do if ! grep -q '^	"'"$$c"'"' doc/schemas/listconfigs.schema.json; then echo "$$c documented but not in schema!"; exit 1; fi; done
+
 doc-maintainer-clean:
 	$(RM) $(MANPAGES)
 

diff --git a/doc/STYLE.md b/doc/STYLE.md
@@ -194,6 +194,12 @@ All `warning` fields should have unique names which start with
 `warning_`, the value of which should be an explanation.  This allows
 for programs to deal with them sanely, and also perform translations.
 
+### Documenting JSON APIs
+
+We use JSON schemas to validate that JSON-RPC returns are in the
+correct form, and also to generate documentation.  See
+[doc/schemas/WRITING_SCHEMAS.md](WRITING_SCHEMAS.md).
+
 ## Changing JSON APIs
 
 All JSON API changes need a Changelog line (see below).

diff --git a/doc/lightning-addgossip.7 b/doc/lightning-addgossip.7
diff --git a/doc/lightning-addgossip.7.md b/doc/lightning-addgossip.7.md
@@ -41,4 +41,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:f974a3848c4db5b73fffa969a741ef6619c9a375783fabe731882d84a6bbf5ff)
+[comment]: # ( SHA256STAMP:f807f98a54c194fab710f8a3393e96685fdbd0efa5e178cca54507a70a7a5c20)
diff --git a/doc/lightning-autocleaninvoice.7 b/doc/lightning-autocleaninvoice.7
diff --git a/doc/lightning-autocleaninvoice.7.md b/doc/lightning-autocleaninvoice.7.md
@@ -49,4 +49,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:2accf7788133af97ae097f7e4e8a80b35bbb431eb7e787e5ae12dd5c7d2c296d)
+[comment]: # ( SHA256STAMP:b03847eff3fac04edb72f6ef86b31a2d05c077a8771845717a26f463ebed4ae7)
diff --git a/doc/lightning-check.7 b/doc/lightning-check.7
diff --git a/doc/lightning-check.7.md b/doc/lightning-check.7.md
@@ -39,4 +39,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:5b399ee88a5fb6b7eac0e1ac349a68a8715154f8c6468aedf446c703c91ac165)
+[comment]: # ( SHA256STAMP:3dd679aceebf5dca6daabc1b28a0f95c413daa9a689bf55270b38b57f0b17957)
diff --git a/doc/lightning-checkmessage.7 b/doc/lightning-checkmessage.7
diff --git a/doc/lightning-checkmessage.7.md b/doc/lightning-checkmessage.7.md
@@ -23,17 +23,16 @@ efficiently than trying each one, so performance is not a concern.
 RETURN VALUE
 ------------
 
-On correct usage, an object with attribute *verified* will be
-returned.
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+- **verified** (boolean): Whether the signature was valid
 
-If *verified* is true, the signature was generated by the returned
-*pubkey* for that given message.  *pubkey* is the one specified as
-input, or if none was specified, the known node which must have
-produced this signature.
+If **verified** is *true*:
+  - **pubkey** (pubkey): the *pubkey* parameter, or the pubkey found by looking for known nodes
 
-If *verified* is false, the signature is meaningless.  *pubkey* may
-also be returned, which is they *pubkey* (if any) for which this
-signature would be valid.  This is usually not useful.
+If **verified** is *false*:
+  - **pubkey** (pubkey): the *pubkey* (if any) which could have signed this; this is usually not useful!
+[comment]: # (GENERATE-FROM-SCHEMA-END)
 
 AUTHOR
 ------
@@ -50,3 +49,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
+[comment]: # ( SHA256STAMP:7c0607f4a7d11de4c9d4cac0e56df8475c0a14e9f1ce70d7fc49322a5b184901)
diff --git a/doc/lightning-close.7 b/doc/lightning-close.7
diff --git a/doc/lightning-close.7.md b/doc/lightning-close.7.md
@@ -107,4 +107,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:9159304cd705d8135c32e12bd029c0e95baff0d495e6f9092a75888dab2f5fb3)
+[comment]: # ( SHA256STAMP:d590b312dff1e1fb4e0bf5540d04bfa4925f6cba51bef6664a642e382ec257d9)
diff --git a/doc/lightning-connect.7 b/doc/lightning-connect.7
diff --git a/doc/lightning-connect.7.md b/doc/lightning-connect.7.md
@@ -88,4 +88,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:5b168e7998d3db6a842eabf92bcbb74352fe831726ea42a801e39ff5c3f812ca)
+[comment]: # ( SHA256STAMP:973f366e2f87becdece4ba3b71f9a5156529d7c155bb8fcac0d2b6662a9e467d)
diff --git a/doc/lightning-createinvoice.7 b/doc/lightning-createinvoice.7
diff --git a/doc/lightning-createinvoice.7.md b/doc/lightning-createinvoice.7.md
@@ -72,4 +72,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:95a2fbf9c94fa1e01a322658035473c694bfb93e02d32c2cefafe6ef5b676695)
+[comment]: # ( SHA256STAMP:948d344d5f589050127bd5181689882c6fad036799fa6ff039a83194ff5fd098)
diff --git a/doc/lightning-createonion.7 b/doc/lightning-createonion.7
diff --git a/doc/lightning-createonion.7.md b/doc/lightning-createonion.7.md
@@ -135,4 +135,4 @@ RESOURCES
 Main web site: <https://github.com/ElementsProject/lightning>
 
 [bolt04]: https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md
-[comment]: # ( SHA256STAMP:a5a64325f4232f27bccbbe1c9fc62bfb602ba60c81f46a1ef2df25b06dac807e)
+[comment]: # ( SHA256STAMP:68e54caa71beb0445389b61d8b384e40ec91e7569d4e2f2de05ed7612713ee64)
diff --git a/doc/lightning-decode.7 b/doc/lightning-decode.7
diff --git a/doc/lightning-decode.7.md b/doc/lightning-decode.7.md
@@ -183,4 +183,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:733d22404e5230882682b846ace92451d8988cf028fa903d735f61b7c61f1c08)
+[comment]: # ( SHA256STAMP:f0adee97f3b5776059252703efee1b8e244c1141f9f3dd5fe73e3d7ed4d59ab4)
diff --git a/doc/lightning-decodepay.7 b/doc/lightning-decodepay.7
diff --git a/doc/lightning-decodepay.7.md b/doc/lightning-decodepay.7.md
@@ -68,4 +68,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:33a160a1d9e56690e59b71c4d9d3e141bf7604c111cd5a5624bda692b85c9026)
+[comment]: # ( SHA256STAMP:435b2a155971979a75be7e9aefc5a686795c3ab210b94af72cf069bd5f3bcefc)
diff --git a/doc/lightning-delexpiredinvoice.7 b/doc/lightning-delexpiredinvoice.7
diff --git a/doc/lightning-delexpiredinvoice.7.md b/doc/lightning-delexpiredinvoice.7.md
@@ -37,4 +37,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:f267fd509a5e3e55e2322ddc8b233eb820638ed5f50f606e3e6c8ae17f1c8421)
+[comment]: # ( SHA256STAMP:644749218693cab4f48f6557a908aba66ae32f6b769576345f66ad62a6c7e7e0)
diff --git a/doc/lightning-delinvoice.7 b/doc/lightning-delinvoice.7
diff --git a/doc/lightning-delinvoice.7.md b/doc/lightning-delinvoice.7.md
@@ -23,10 +23,13 @@ Note: The return is the same as an object from lightning-listinvoice(7).
 [comment]: # (GENERATE-FROM-SCHEMA-START)
 On success, an object is returned, containing:
 - **label** (string): Unique label given at creation time
+- **payment_hash** (hex): the hash of the *payment_preimage* which will prove payment (always 64 characters)
 - **status** (string): State of invoice (one of "paid", "expired", "unpaid")
 - **expires_at** (u64): UNIX timestamp when invoice expires (or expired)
 - **bolt11** (string, optional): BOLT11 string
 - **bolt12** (string, optional): BOLT12 string
+- **amount_msat** (msat, optional): the amount required to pay this invoice
+- **description** (string, optional): description used in the invoice
 
 If **bolt12** is present:
   - **local_offer_id** (hex, optional): offer for which this invoice was created
@@ -68,4 +71,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:8cd84ec57d229dacb6d6c52510334da87846f1c8eea7db286063a2513e8318cb)
+[comment]: # ( SHA256STAMP:6435d88007d1b21e97c969cc202e240ed57df572a3312a6b77ea66ed3a8d512a)
diff --git a/doc/lightning-delpay.7 b/doc/lightning-delpay.7
diff --git a/doc/lightning-delpay.7.md b/doc/lightning-delpay.7.md
@@ -99,4 +99,4 @@ RESOURCES
 ---------
 
 Main web site: <https://github.com/ElementsProject/lightning>
-[comment]: # ( SHA256STAMP:26e293e5b3de31a95572763a6d7c360c0f9f78112b3fcef12c639d001b0fa9b5)
+[comment]: # ( SHA256STAMP:c3a603b1e43a370ff38a3d9eebe63f8acf26447b024cf5e4bd6f93fe41632529)
diff --git a/doc/lightning-dev-sendcustommsg.7 b/doc/lightning-dev-sendcustommsg.7
diff --git a/doc/lightning-dev-sendcustommsg.7.md b/doc/lightning-dev-sendcustommsg.7.md
@@ -47,6 +47,11 @@ as the message is queued.
 If any of the above limitations is not respected the method returns an
 explicit error message stating the issue.
 
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+- **status** (string): Information about where message was queued
+[comment]: # (GENERATE-FROM-SCHEMA-END)
+
 AUTHOR
 ------
 
@@ -62,3 +67,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
+[comment]: # ( SHA256STAMP:28ff2cdde9b35e81ceec3b1860facb1b2f91c5049ce33776b3c992621aba475d)
diff --git a/doc/lightning-disableoffer.7 b/doc/lightning-disableoffer.7
diff --git a/doc/lightning-disableoffer.7.md b/doc/lightning-disableoffer.7.md
@@ -72,4 +72,4 @@ RESOURCES
 ---------
 
 Main web site: <https://github.com/ElementsProject/lightning>
-[comment]: # ( SHA256STAMP:6b0ae21e38a83742735f38e9c022b33ed4a436cacc746ff22e63d7b00779e4d0)
+[comment]: # ( SHA256STAMP:abf340bf35dcefd42fba609b3ae95adb2f74bb5766c68e174a9b8f9114c80202)
diff --git a/doc/lightning-disconnect.7 b/doc/lightning-disconnect.7
diff --git a/doc/lightning-disconnect.7.md b/doc/lightning-disconnect.7.md
@@ -58,4 +58,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:f974a3848c4db5b73fffa969a741ef6619c9a375783fabe731882d84a6bbf5ff)
+[comment]: # ( SHA256STAMP:f807f98a54c194fab710f8a3393e96685fdbd0efa5e178cca54507a70a7a5c20)
diff --git a/doc/lightning-feerates.7 b/doc/lightning-feerates.7
diff --git a/doc/lightning-feerates.7.md b/doc/lightning-feerates.7.md
@@ -118,4 +118,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:e16ae963e528995f1e01c80b4ed4e9b0d6c457a559928e98ab6cf32624557894)
+[comment]: # ( SHA256STAMP:b7efbc2380ce39e1d8f244a9c16203f034d53b84f8396f4c4fc06973d24cefe4)
diff --git a/doc/lightning-fetchinvoice.7 b/doc/lightning-fetchinvoice.7
diff --git a/doc/lightning-fetchinvoice.7.md b/doc/lightning-fetchinvoice.7.md
@@ -81,4 +81,4 @@ RESOURCES
 
 Main web site: <https://github.com/ElementsProject/lightning>
 
-[comment]: # ( SHA256STAMP:e2b81ad7a61dd6a6d55e21c5367c3286aaf00cee734b2719a8e38bc87f7ac8aa)
+[comment]: # ( SHA256STAMP:c98a6dd644a23fb336aa2ce190e15ae602da8b4142afbed28e4243114f679e90)
diff --git a/doc/lightning-fundchannel.7 b/doc/lightning-fundchannel.7