[Emacs-diffs] master 7c317c8 2/2: Clarify json-read and json-encode parameters and return values

[Lars Ingebrigtsen]

branch: master
commit 7c317c835ad506ec0e1029836b19fbbca9e0ae3b
Author: Lars Ingebrigtsen <address@hidden>
Commit: Lars Ingebrigtsen <address@hidden>

    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.
---
 lisp/json.el | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/lisp/json.el b/lisp/json.el
index 44b3c33..d3655a0 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))