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

[Dmitry Gutov]

Hi Eli,

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
> -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'.

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.