From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state" Date: Tue, 2 Jul 2019 11:05:18 -0700 (PDT) Message-ID: <13f5f7df-9017-45a0-986f-8b1a4ee0e9bd@default> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="36604"; mail-complaints-to="usenet@blaine.gmane.org" To: 36478@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Jul 02 21:20:29 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1hiOKK-0009MV-Je for geb-bug-gnu-emacs@m.gmane.org; Tue, 02 Jul 2019 21:20:28 +0200 Original-Received: from localhost ([::1]:56474 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hiOKI-0008I7-8C for geb-bug-gnu-emacs@m.gmane.org; Tue, 02 Jul 2019 15:20:26 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:50045) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hiNAY-000400-K2 for bug-gnu-emacs@gnu.org; Tue, 02 Jul 2019 14:06:19 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hiNAO-0007ba-9O for bug-gnu-emacs@gnu.org; Tue, 02 Jul 2019 14:06:14 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:39081) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hiNAI-0007XA-MA for bug-gnu-emacs@gnu.org; Tue, 02 Jul 2019 14:06:05 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hiNAI-0000JM-DJ for bug-gnu-emacs@gnu.org; Tue, 02 Jul 2019 14:06:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 02 Jul 2019 18:06:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 36478 X-GNU-PR-Package: emacs X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.15620907471168 (code B ref -1); Tue, 02 Jul 2019 18:06:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 2 Jul 2019 18:05:47 +0000 Original-Received: from localhost ([127.0.0.1]:47902 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hiNA3-0000Im-Dg for submit@debbugs.gnu.org; Tue, 02 Jul 2019 14:05:47 -0400 Original-Received: from lists.gnu.org ([209.51.188.17]:50889) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hiNA1-0000Ic-3A for submit@debbugs.gnu.org; Tue, 02 Jul 2019 14:05:45 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:49792) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hiN9u-0003uG-8t for bug-gnu-emacs@gnu.org; Tue, 02 Jul 2019 14:05:41 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hiN9p-000789-Un for bug-gnu-emacs@gnu.org; Tue, 02 Jul 2019 14:05:38 -0400 Original-Received: from userp2120.oracle.com ([156.151.31.85]:34674) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1hiN9o-0006xK-8z for bug-gnu-emacs@gnu.org; Tue, 02 Jul 2019 14:05:32 -0400 Original-Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x62I3xFL012300 for ; Tue, 2 Jul 2019 18:05:21 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : subject : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=JUNhW9L0pkTXpJ6AkDZ+/DPTw+dxn3K8iLcme7eZBCc=; b=RoXpSnXgduEL0pLqTUYKo3Q+BOjxlh46mVDG7jDsWK8SkGuYl+4UBx6aP9jih7d2tSze HeDXqQ9yqq6GKW+QTrGUeK4ZDPyO+PMnpZ5vSsI3ew9Uoo1ggOno+zYAfBdFHVse3sL+ ZwHJTWFF4mAYRFyu5Smcbh0R8ONKeej70NYnpJzij2Sr2u/AN4yQ5czAjkIjiqrQUt0C NUSw+/CfqqWXcMs6uvdYdroLjegZ9pD5/NGfBsnTlVuIbdJxaCdf8tnOn/t2b/i9vi12 tihJQcG1nBFt8C1faDE9R0NhD44ywBCiom2bHfZI9g0817LhAd3tlMbVDsE4CFYa0+eI /A== Original-Received: from aserp3020.oracle.com (aserp3020.oracle.com [141.146.126.70]) by userp2120.oracle.com with ESMTP id 2te61pw87r-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Tue, 02 Jul 2019 18:05:21 +0000 Original-Received: from pps.filterd (aserp3020.oracle.com [127.0.0.1]) by aserp3020.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x62I39VS088672 for ; Tue, 2 Jul 2019 18:05:20 GMT Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserp3020.oracle.com with ESMTP id 2tebkudq2k-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Tue, 02 Jul 2019 18:05:20 +0000 Original-Received: from abhmp0016.oracle.com (abhmp0016.oracle.com [141.146.116.22]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id x62I5JOS020075 for ; Tue, 2 Jul 2019 18:05:19 GMT X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4861.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9306 signatures=668688 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=1 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1907020199 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9306 signatures=668688 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=1 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1907020199 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:161977 Archived-At: `C-h f zerop' tells you this: zerop is a compiled Lisp function in 'subr.el'. (zerop NUMBER) This function has a compiler macro 'zerop--anon-cmacro'. Return t if NUMBER is zero. This function does not change global state, including the match data. Why on earth would we put that info about the function having a compiler macro before the first doc string line? What does it even mean? Searching for "compiler macro" in the Elisp manual I find mention of it (in passing only) in node `Defining Functions', but no definition of it. And there's no index entry for it, AFAICT. Reading that node, I still don't know what "compiler macro" really means. Perhaps it means code that inlines a function definition at byte-compilation time? That whole node `Defining Functions' is pretty much incomprehensible now, with the additions about ...inline.... Compare node `Inline Functions', which is quite clear. For example: Functions defined via 'define-inline' have several advantages with respect to macros defined by 'defsubst' or 'defmacro'... Huh? `defsubst' defines macros? I don't think so. I think a node should probably be dedicated to `define-inline' or to whatever it does. The concepts really need to be developed. Putting this, whatever it is, in with `defun' in the main node about defining functions does users, especially newbies, a disservice. The help for a function (e.g. `zerop') should, after showing the signature, start with the doc string, which says what the function does. The help should not start by providing peripheral info about the function. Putting this info first doesn't follow Emacs longstanding help convention. Not to mention that if you click that `zerop--anon-cmacro' link you get this: zerop--anon-cmacro is a compiled Lisp function in 'subr.el'. (zerop--anon-cmacro _ NUMBER) Not documented. What's more: if you click the `subr.el' link you get nowhere that tells you anything about `zerop--anon-cmacro' - there are no occurrences of `zerop--anon-cmacro' in that file. Wunderbar. Thanks for the help, Emacs! This is a real mess - doesn't help users. Instead, it gets in their way. Please DTRT. Either get rid of such obscurantism or put it at the end of the `C-h f' output and fix its useless links. --- In addition, why do we automatically add the following sentence to the help (without even an intervening blank line), as if it were the second doc-string line: This function does not change global state, including the match data. Who asked for that? Which functions get that added to their doc strings? Every function for which that's true? I doubt that, and if I'm right then the fact that some functions do get that added is misleading. In GNU Emacs 26.2 (build 1, x86_64-w64-mingw32) of 2019-04-13 Repository revision: fd1b34bfba8f3f6298df47c8e10b61530426f749 Windowing system distributor `Microsoft Corp.', version 10.0.17134 Configured using: `configure --without-dbus --host=3Dx86_64-w64-mingw32 --without-compress-install 'CFLAGS=3D-O2 -static -g3''