> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Mon, 18 Dec 2017 19:55:52 +0000
> Cc: raman@google.com, emacs-devel@gnu.org
>
>    @defun json-parse-string string &key (object-type @code{hash-table})
>
>  ?
>
> If that's the right thing, sure. OTOH, cl.texi uses
> @defun cl-fill seq item @t{&key :start :end}
> so probably we should use that?

No, @t is almost never right, certainly not in code sequences.

>  >  >  > +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.
>
> OK, what's your suggestion?

I thought I wrote that above.