From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: JSON->lisp Mapping: Hash vs AList Date: Sun, 17 Dec 2017 22:07:23 +0200 Message-ID: <834lopqft0.fsf@gnu.org> References: <838te5uvee.fsf@gnu.org> <838te1qrkq.fsf@gnu.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1513541145 19653 195.159.176.226 (17 Dec 2017 20:05:45 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 17 Dec 2017 20:05:45 +0000 (UTC) Cc: emacs-devel@gnu.org, raman@google.com To: Philipp Stephani Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Dec 17 21:05:40 2017 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eQfBr-0004fm-OP for ged-emacs-devel@m.gmane.org; Sun, 17 Dec 2017 21:05:39 +0100 Original-Received: from localhost ([::1]:55337 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eQfDo-0001TH-E8 for ged-emacs-devel@m.gmane.org; Sun, 17 Dec 2017 15:07:40 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:52298) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eQfDe-0001TA-Sf for emacs-devel@gnu.org; Sun, 17 Dec 2017 15:07:31 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eQfDb-0000OA-HM for emacs-devel@gnu.org; Sun, 17 Dec 2017 15:07:30 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:52248) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eQfDb-0000Nm-D5; Sun, 17 Dec 2017 15:07:27 -0500 Original-Received: from [176.228.60.248] (port=4730 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1eQfDZ-0007cz-KJ; Sun, 17 Dec 2017 15:07:27 -0500 In-reply-to: (message from Philipp Stephani on Sun, 17 Dec 2017 17:44:34 +0000) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:221184 Archived-At: > From: Philipp Stephani > 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.