> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Sat, 16 Dec 2017 22:24:35 +0000
> Cc: raman@google.com, emacs-devel@gnu.org
>
>  > -@defun json-parse-string string
>  > +@defun json-parse-string string &key (object-type 'hash-table)
>
>  Hmm.. why is there an apostrophe before "hash-table"?  What do you
>  want to get in the output there?
>
> An apostrophe? It seems to work as expected.

That's not what I meant.  I meant we never use a bare apostrophe in
Texinfo, we use markup instead.  So I asked what you want to get there
in the Info and printed output, so I could suggest a proper markup.

>  And btw, I don't see "&key" mentioned anywhere in the ELisp manual, so
>  I wonder whether the reader will understand what it means.
>
> This is the Common Lisp syntax, from cl-defun etc. It's a bit unfortunate that it's not used in Emacs core, even
> for functions that take keyword arguments such as `make-process'. I can switch to '&rest args' if you prefer
> that.

Let's wait until the discussion of using &key in the code reaches its
conclusion.  If &key will stay in the source, I do prefer &rest in the
manual.

>  > +              result = Fnreverse (result);
>
>  Is there a reason for calling nreverse here?
>
> It puts the elements in the same order as the original JSON. (The Jansson parser also retains the original
> order.)
> This isn't very important, just a bit nicer and less surprising.

It's a potential performance hit, but if you think it's worthwhile,
it's fine with me.

>  > +The keyword argument OBJECT-TYPE specifies which Lisp type is used to
>                          ^^^^^^^^^^^
>  Shouldn't that be `:object-type' (including quotes)?
>
> Depending on whether we can use &key in a docstring in core. If so, then this one is correct, see e.g. the
> docstring of should-error.

IMO, the doc string of should-error is no less confusing than this
one, because it expects something like ":type 'foo".