[Emacs-diffs] master 2475687: Improve documentation changes of a recent commit

[Eli Zaretskii]

branch: master
commit 2475687d2f0ca6a605d091bb7acb723d0dace27b
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve documentation changes of a recent commit
    
    * doc/lispref/text.texi (Parsing JSON): Improve wording of the
    documentation of 'json-parse-string' and 'json-parse-buffer'.
    * src/json.c (Fjson_parse_string, Fjson_parse_buffer): Doc fix.
    (Bug#34763)
---
 doc/lispref/text.texi | 13 ++++++++-----
 src/json.c            | 42 ++++++++++++++++++++++++++++++++----------
 2 files changed, 40 insertions(+), 15 deletions(-)

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index b46ee64..e8de817 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -5156,8 +5156,11 @@ as in @code{json-parse-string}.
 
 @defun json-parse-string string &rest args
 This function parses the JSON value in @var{string}, which must be a
-Lisp string.  The argument @var{args} is a list of keyword/argument
-pairs.  The following keywords are accepted:
+Lisp string.  If @var{string} doesn't contain a valid JSON object,
+this function signals the @code{json-parse-error} error.
+
+The argument @var{args} is a list of keyword/argument pairs.  The
+following keywords are accepted:
 
 @table @code
 @item :object-type
@@ -5186,9 +5189,9 @@ keyword @code{false}.  It defaults to the symbol 
@code{:false}.
 @defun json-parse-buffer &rest args
 This function reads the next JSON value from the current buffer,
 starting at point.  It moves point to the position immediately after
-the value if a value could be read and converted to Lisp; otherwise it
-doesn't move point.  The arguments @var{args} are interpreted as in
address@hidden
+the value if contains a valid JSON object; otherwise it signals the
address@hidden error and doesn't move point.  The arguments
address@hidden are interpreted as in @code{json-parse-string}.
 @end defun
 
 @node JSONRPC
diff --git a/src/json.c b/src/json.c
index eb323b4..74e0534 100644
--- a/src/json.c
+++ b/src/json.c
@@ -948,23 +948,22 @@ json_to_lisp (json_t *json, struct json_configuration 
*conf)
 DEFUN ("json-parse-string", Fjson_parse_string, Sjson_parse_string, 1, MANY,
        NULL,
        doc: /* Parse the JSON STRING into a Lisp object.
-
 This is essentially the reverse operation of `json-serialize', which
-see.  The returned object will be a vector, hashtable, alist, or
+see.  The returned object will be a vector, list, hashtable, alist, or
 plist.  Its elements will be the JSON null value, the JSON false
 value, t, numbers, strings, or further vectors, hashtables, alists, or
 plists.  If there are duplicate keys in an object, all but the last
-one are ignored.  If STRING doesn't contain a valid JSON object, an
-error of type `json-parse-error' is signaled.  The arguments ARGS are
-a list of keyword/argument pairs:
+one are ignored.  If STRING doesn't contain a valid JSON object, this
+function signals an error of type `json-parse-error'.
+
+The arguments ARGS are a list of keyword/argument pairs:
 
 The keyword argument `:object-type' specifies which Lisp type is used
 to represent objects; it can be `hash-table', `alist' or `plist'.  It
 defaults to `hash-table'.
 
 The keyword argument `:array-type' specifies which Lisp type is used
-to represent arrays; it can be `array' or `list'.  It defaults to
-`array'.
+to represent arrays; it can be `array' (the default) or `list'.
 
 The keyword argument `:null-object' specifies which object to use
 to represent a JSON null value.  It defaults to `:null'.
@@ -1042,9 +1041,32 @@ json_read_buffer_callback (void *buffer, size_t buflen, 
void *data)
 DEFUN ("json-parse-buffer", Fjson_parse_buffer, Sjson_parse_buffer,
        0, MANY, NULL,
        doc: /* Read JSON object from current buffer starting at point.
-This is similar to `json-parse-string', which see.  Move point after
-the end of the object if parsing was successful.  On error, point is
-not moved.
+Move point after the end of the object if parsing was successful.
+On error, don't move point.
+
+The returned object will be a vector, list, hashtable, alist, or
+plist.  Its elements will be the JSON null value, the JSON false
+value, t, numbers, strings, or further vectors, lists, hashtables,
+alists, or plists.  If there are duplicate keys in an object, all
+but the last one are ignored.
+
+If the current buffer doesn't contain a valid JSON object, the
+function signals an error of type `json-parse-error'.
+
+The arguments ARGS are a list of keyword/argument pairs:
+
+The keyword argument `:object-type' specifies which Lisp type is used
+to represent objects; it can be `hash-table', `alist' or `plist'.  It
+defaults to `hash-table'.
+
+The keyword argument `:array-type' specifies which Lisp type is used
+to represent arrays; it can be `array' (the default) or `list'.
+
+The keyword argument `:null-object' specifies which object to use
+to represent a JSON null value.  It defaults to `:null'.
+
+The keyword argument `:false-object' specifies which object to use to
+represent a JSON false value.  It defaults to `:false'.
 usage: (json-parse-buffer &rest args) */)
      (ptrdiff_t nargs, Lisp_Object *args)
 {