From 7c317c835ad506ec0e1029836b19fbbca9e0ae3b Mon Sep 17 00:00:00 2001 From: Lars Ingebrigtsen Date: Tue, 9 Jul 2019 19:41:06 +0200 Subject: 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(-) (limited to 'lisp/json.el') 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)) -- cgit v1.2.3