Re: JSON->lisp Mapping: Hash vs AList

[Eli Zaretskii <eliz@gnu.org>]

> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Sun, 17 Dec 2017 17:44:34 +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.
> 
> My goal was to specify the default value the same way that cl-lib does. With cl-lib you'd write the function as 
> 
> (cl-defun json-parse-string (string &key (object-type 'hash-table)))
> 
> We can't do that in C, but we can keep the same syntax.

We are miscommunicating.  I'm talking about Texinfo markup, not about
Lisp or C code.  In Texinfo manuals dedicated to Emacs we use
@code{foo} where in Lisp you'd write 'foo.  Why not in this case?
IOW, why not use

  @defun json-parse-string string &key (object-type @code{hash-table})

?

>  >  > +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".
> 
> Arguably yes. Though that has been the convention for cl-lib functions for a while. 

cl-lib enjoyed being in the shadows for too long.  I don't think we
should let that continue any longer, we should fix that.