Eli Zaretskii <
address@hidden> schrieb am So., 17. Dez. 2017 um 16:53 Uhr:
> From: Philipp Stephani <address@hidden>
> Date: Sat, 16 Dec 2017 22:24:35 +0000
> Cc: address@hidden, address@hidden
>
> > address@hidden json-parse-string string
> > address@hidden 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.
> 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.
I think the discussion will reach a conclusion if and when you or John as maintainers make a decision :-)
> > + 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.
I don't care much. For now I'd leave it in, we can take it out later if it hurts performance too much. (Though people that care about performance should probably use hashtables anyway.)
> > +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.