Clarify json-read and json-encode parameters and return values

* lisp/json.el (json-read): Try to clarify what's returned (bug#34242).
(json-encode): Refer to `json-read' about what the input is and
say what error is signalled.

1 files changed, 18 insertions, 2 deletions

diff --git a/lisp/json.el b/lisp/json.el
index 44b3c33df7c..d3655a0f26c 100644
--- a/lisp/json.el
+++ b/lisp/json.el
@@ -691,7 +691,19 @@ become JSON objects."
 
 (defun json-read ()
   "Parse and return the JSON object following point.
-Advances point just past JSON object."
+Advances point just past JSON object.
+
+If called with the following JSON after point
+
+  {\"a\": [1, 2, {\"c\": false}],
+   \"b\": \"foo\"}
+
+you will get the following structure returned:
+
+  ((a .
+      [1 2
+         ((c . :json-false))])
+   (b . \"foo\"))"
   (json-skip-whitespace)
   (let ((char (json-peek)))
     (if (zerop char)
@@ -719,7 +731,11 @@ Advances point just past JSON object."
 ;;; JSON encoder
 
 (defun json-encode (object)
-  "Return a JSON representation of OBJECT as a string."
+  "Return a JSON representation of OBJECT as a string.
+
+OBJECT should have a structure like one returned by `json-read'.
+If an error is detected during encoding, an error based on
+`json-error' is signalled."
   (cond ((memq object (list t json-null json-false))
          (json-encode-keyword object))
         ((stringp object)      (json-encode-string object))