From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Philipp Stephani
> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Sat, 16 Dec 2017 22:24:35 +0000
> Cc: raman@google= .com, emacs-de= vel@gnu.org
>
>=C2=A0 > -@defun json-parse-string string
>=C2=A0 > +@defun json-parse-string string &key (object-type '= ;hash-table)
>
>=C2=A0 Hmm.. why is there an apostrophe before "hash-table"?= =C2=A0 What do you
>=C2=A0 want to get in the output there?
>
> An apostrophe? It seems to work as expected.
That's not what I meant.=C2=A0 I meant we never use a bare apostrophe i= n
Texinfo, we use markup instead.=C2=A0 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 s= ame way that cl-lib does. With cl-lib you'd write the function as=C2=A0=(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.=C2=A0
>=C2=A0 And btw, I don't see "&key" mentioned anywhere= in the ELisp manual, so
>=C2=A0 I wonder whether the reader will understand what it means.
>
> This is the Common Lisp syntax, from cl-defun etc. It's a bit unfo= rtunate 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 i= ts
conclusion.=C2=A0 If &key will stay in the source, I do prefer &res= t in the
manual.
>=C2=A0 > +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 result = =3D Fnreverse (result);
>
>=C2=A0 Is there a reason for calling nreverse here?
>
> It puts the elements in the same order as the original JSON. (The Jans= son 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.
>=C2=A0 > +The keyword argument OBJECT-TYPE specifies which Lisp type= is used to
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 ^^^^^^^^^^^
>=C2=A0 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 conventi= on for cl-lib functions for a while.=C2=A0