[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Emacs-diffs] master 2475687: Improve documentation changes of a rec
Re: [Emacs-diffs] master 2475687: Improve documentation changes of a recent commit
Sun, 14 Apr 2019 13:34:51 +0300
Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.6.1
On 13.04.2019 10:09, Eli Zaretskii wrote:
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
+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'.
FTR, I quite dislike this kind of duplication in docstrings.
Didn't we discuss the difference between docstrings and manuals some
time ago, where you expressed the opinion that docstrings are allowed
the kind of "see XX for more detail" references, and it's the manuals
where information sometimes has to be reiterated for the convenience of
the reader? Here you seem to have made the reverse choice.
- Re: [Emacs-diffs] master 2475687: Improve documentation changes of a recent commit,
Dmitry Gutov <=