From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: Poor quality documentation in edebug.el, and recursive documentation. Date: Wed, 06 May 2020 14:20:15 -0400 Message-ID: References: <20200505202048.GA15482@ACM> <6674ab3a-9107-d59f-5758-2fd5961cfbcc@gmail.com> <20200506170134.GB5741@ACM> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="66907"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) Cc: =?windows-1252?Q?Cl=E9ment?= Pit-Claudel , emacs-devel@gnu.org To: Alan Mackenzie Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Wed May 06 20:21:52 2020 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jWOg3-000HIN-J3 for ged-emacs-devel@m.gmane-mx.org; Wed, 06 May 2020 20:21:51 +0200 Original-Received: from localhost ([::1]:40994 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jWOg2-0000VS-Io for ged-emacs-devel@m.gmane-mx.org; Wed, 06 May 2020 14:21:50 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:58346) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jWOee-0008Js-4L for emacs-devel@gnu.org; Wed, 06 May 2020 14:20:24 -0400 Original-Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:42834) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jWOea-0008Jm-Qi for emacs-devel@gnu.org; Wed, 06 May 2020 14:20:23 -0400 Original-Received: from pmg2.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id 1C4D680629; Wed, 6 May 2020 14:20:19 -0400 (EDT) Original-Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id 2F75580063; Wed, 6 May 2020 14:20:17 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1588789217; bh=xaKclBiwhtoY5HYgoubg2P16zYoyy2Xgjtpyhq7jj1k=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=aiu7AjCE+9iMNt+j+KPdfw8r2/KIiSetsBAjWrS4ZMVPQGzZ4Zvv2MCrsKxnvj5Jp zcyEZ0CcEEPntfT0f6IssmRO03TDnbBKqbb/blCvFSbfOpchvR1eJ5L6lWeu3Qkn5Z J5m/vPz05hpBKQPm/cSbrC3TB7WiV4k6tYHmOIYJUp+GYKYuWIJAEoTeyQ2FjhEW/c BBYZiFJthGDJ8wA+ptLPM1AVMOsWii/sGh1TbdlF/xMNAI3yIuoSVHJ6AySa9ePKLP Dwyl3L3vPImfhXufF/zDdQkLiIpX85qWowT/jlWAZ6GLFozkRWvwRi66J3E+UUfgnj Wb6fDOj3FBVNg== Original-Received: from alfajor (unknown [216.154.3.202]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id C84D61207EA; Wed, 6 May 2020 14:20:16 -0400 (EDT) In-Reply-To: <20200506170134.GB5741@ACM> (Alan Mackenzie's message of "Wed, 6 May 2020 17:01:34 +0000") Received-SPF: pass client-ip=132.204.25.50; envelope-from=monnier@iro.umontreal.ca; helo=mailscanner.iro.umontreal.ca X-detected-operating-system: by eggs.gnu.org: First seen = 2020/05/06 09:28:21 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] X-Spam_score_int: -42 X-Spam_score: -4.3 X-Spam_bar: ---- X-Spam_report: (-4.3 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_MED=-2.3, SPF_PASS=-0.001, URIBL_BLOCKED=0.001 autolearn=_AUTOLEARN X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 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-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:249109 Archived-At: >> Really? You're looking at the documentation of a field accessor =E2=80= =94 can >> it be made much better (sort of writing it by hand)? > It could be made much better. For a start, it shouldn't be > syntactically ambiguous - It could be talking about "an access slot" or > "accessing the slot". I think you're telling me that the second is > meant. I'm not sure what that would look like in practice. I may be to blame for the current wording and I'm definitely not wedded to it, so I'd welcome concrete suggestions. For the record, part of the motivation for the current wording is that traditionally the first line of the docstring of a function describes concisely what the function *does* in the present/imperative tense. So "an access slot" or "accessing the slot" would be quite unusual. I don't have strong feelings about whether such unusual would be good or not, but I think other people might. > And why such a woolly, meaningless word like "access"? Are we talking > about a read access or a write access here? Actually it works for both since it's a "place" (i.e. it works with `setf`, `push`, ...). > Now people have explained it, I see that it means "return the value of > the slot def-name". That is explicit and says what is done. > Why can that not be written? Sounds fine to me, yes. Any objection to the patch below? > And why is the edebug--frame's metasyntactic variable called CL-X? If > somebody were trying deliberately to be unhelpful, that is what they > would call it. I answered this in an earlier message, which I assume you've read since. Stefan diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el index 4408bb58464..237d85b81d3 100644 --- a/lisp/emacs-lisp/cl-macs.el +++ b/lisp/emacs-lisp/cl-macs.el @@ -2899,7 +2899,7 @@ cl-defstruct ;; The arg "cl-x" is referenced by name in eg pred-form ;; and pred-check, so changing it is not straightforward. (push `(,defsym ,accessor (cl-x) - ,(format "Access slot \"%s\" of `%s' struct CL-X.%s" + ,(format "Return value of the slot \"%s\" of `%s' s= truct CL-X.%s" slot name (if doc (concat "\n" doc) "")) (declare (side-effect-free t))