From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel Subject: Re: [Emacs-diffs] master 2475687: Improve documentation changes of a recent commit Date: Sun, 14 Apr 2019 13:34:51 +0300 Message-ID: References: <20190413070933.31645.83730@vcs0.savannah.gnu.org> <20190413070934.DDF7B202C6@vcs0.savannah.gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="97395"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.6.1 To: emacs-devel@gnu.org, Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Apr 14 12:35:43 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1hFcUA-000PDu-RF for ged-emacs-devel@m.gmane.org; Sun, 14 Apr 2019 12:35:42 +0200 Original-Received: from localhost ([127.0.0.1]:33911 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hFcU9-0001Fl-QY for ged-emacs-devel@m.gmane.org; Sun, 14 Apr 2019 06:35:41 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:42245) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hFcTV-0001FH-1g for emacs-devel@gnu.org; Sun, 14 Apr 2019 06:35:02 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hFcTU-0004xF-2G for emacs-devel@gnu.org; Sun, 14 Apr 2019 06:35:01 -0400 Original-Received: from mail-lj1-x236.google.com ([2a00:1450:4864:20::236]:37184) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hFcTR-0004vw-19; Sun, 14 Apr 2019 06:34:57 -0400 Original-Received: by mail-lj1-x236.google.com with SMTP id v13so12872061ljk.4; Sun, 14 Apr 2019 03:34:56 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:subject:to:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=2c+tIkQ+3XO54z+2WaMLXvFPEbsXWNwBAEOLaaykNTM=; b=vemMJRgTwwSawWhn9E5X6gtpRrBkDH7eAOzWErcK6XaJIhNRC1QWrhHGPxiBckyfFC glHTPFCvkEO80jbNj+0TL5UcH0G7IxDBYMCwuKy84clSwYQDU80J031FDKejZKs6IgAA KWMSdCITWAHblw+UD6PJX+G06OYPlR/Ek7StJ6BeDXsq9iCE9jnDG3zHZyNRFowetEz0 LNlWrAr3gByJHtf/5ajE4qdFR27ecwA7VoxEt4TT+U7kZC8hCyeq6D7rPZ122c7dd579 9WgIym/qWyc/PU3b3cGMiNlMGrE2gAFb2bpQjIYl8aYcgBQxQ6bv1xwGj8+LBL8uQh0T 5iZQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:subject:to:references:from:message-id :date:user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=2c+tIkQ+3XO54z+2WaMLXvFPEbsXWNwBAEOLaaykNTM=; b=dzkzqFK7j81jPF0dEIV3LUb9iowrqQAbwcz6Jmky2YTfZU8i5xYjEUNPruvcgfj7CP 7dPG6MAI8dC3mnvQXCRK/GzJCz3eR3yVd0saKjaivUcIKycSJEjPjMXjivlUA+GjywT8 vesDXjcgnnPE0q5t/a1hxkcThz97cEShe0kfTsB5ao+BrRmraVqgEImcPYxTq84F+63b 9Km9KcPhmcWm5SOHTKAGKpMkYrLPIV4aptFxPgS/08e8mxfYbeRxFmdOUQnOQUi+70aA VdUQsE8xTnBl5td1Bd0mQQChBiUshK4jR+zgCGiNeN8lXYtrJ16eRotnR1J+SQ/pyCPC p7rg== X-Gm-Message-State: APjAAAWm1QhJsMpwFu/fcKjKv+uvFNLmQrSk3YbMTyFcsp9Jh0QH+ZCX Jjzzf3r50vf4d8Ij3GwCTQc1/K98 X-Google-Smtp-Source: APXvYqy2HsPeRgpY+vZ4ZPC+c+RevqPyi/BtgqYEcQb5uvs0N4VSIy6iPvHjKkHzt48PzdzyVJ25QA== X-Received: by 2002:a2e:8719:: with SMTP id m25mr7456557lji.50.1555238094652; Sun, 14 Apr 2019 03:34:54 -0700 (PDT) Original-Received: from [192.168.1.3] ([185.105.174.23]) by smtp.googlemail.com with ESMTPSA id f15sm1219619lfa.89.2019.04.14.03.34.52 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sun, 14 Apr 2019 03:34:53 -0700 (PDT) In-Reply-To: <20190413070934.DDF7B202C6@vcs0.savannah.gnu.org> Content-Language: en-US X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::236 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:235432 Archived-At: Hi Eli, On 13.04.2019 10:09, Eli Zaretskii wrote: > doc: /* Read JSON object from current buffer starting at point. > -This is similar to `json-parse-string', which see. Move point after > -the end of the object if parsing was successful. On error, point is > -not moved. > +Move point after the end of the object if parsing was successful. > +On error, don't move point. > + > +The returned object will be a vector, list, hashtable, alist, or > +plist. Its elements will be the JSON null value, the JSON false > +value, t, numbers, strings, or further vectors, lists, hashtables, > +alists, or plists. If there are duplicate keys in an object, all > +but the last one are ignored. > + > +If the current buffer doesn't contain a valid JSON object, the > +function signals an error of type `json-parse-error'. > + > +The arguments ARGS are a list of keyword/argument pairs: > + > +The keyword argument `:object-type' specifies which Lisp type is used > +to represent objects; it can be `hash-table', `alist' or `plist'. It > +defaults to `hash-table'. > + > +The keyword argument `:array-type' specifies which Lisp type is used > +to represent arrays; it can be `array' (the default) or `list'. > + > +The keyword argument `:null-object' specifies which object to use > +to represent a JSON null value. It defaults to `:null'. > + > +The keyword argument `:false-object' specifies which object to use to > +represent a JSON false value. It defaults to `:false'. FTR, I quite dislike this kind of duplication in docstrings. Didn't we discuss the difference between docstrings and manuals some time ago, where you expressed the opinion that docstrings are allowed the kind of "see XX for more detail" references, and it's the manuals where information sometimes has to be reiterated for the convenience of the reader? Here you seem to have made the reverse choice.