From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#42323: 26.3; Doc string of `seq-map' Date: Sat, 11 Jul 2020 09:01:25 -0700 (PDT) Message-ID: Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="39977"; mail-complaints-to="usenet@ciao.gmane.io" To: 42323@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Jul 11 18:04:14 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1juHz3-000AKC-Oa for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 11 Jul 2020 18:04:13 +0200 Original-Received: from localhost ([::1]:44082 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1juHz2-0002ON-PJ for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 11 Jul 2020 12:04:12 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:50774) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1juHww-00082Y-Hk for bug-gnu-emacs@gnu.org; Sat, 11 Jul 2020 12:02:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:33265) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1juHww-0007tH-6E for bug-gnu-emacs@gnu.org; Sat, 11 Jul 2020 12:02:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1juHww-0007yi-2l for bug-gnu-emacs@gnu.org; Sat, 11 Jul 2020 12:02: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: Sat, 11 Jul 2020 16:02:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 42323 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.159448329930634 (code B ref -1); Sat, 11 Jul 2020 16:02:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 11 Jul 2020 16:01:39 +0000 Original-Received: from localhost ([127.0.0.1]:44811 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1juHwV-0007xx-R4 for submit@debbugs.gnu.org; Sat, 11 Jul 2020 12:01:39 -0400 Original-Received: from lists.gnu.org ([209.51.188.17]:51390) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1juHwS-0007xp-RR for submit@debbugs.gnu.org; Sat, 11 Jul 2020 12:01:34 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:50696) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1juHwS-0007Jz-HU for bug-gnu-emacs@gnu.org; Sat, 11 Jul 2020 12:01:32 -0400 Original-Received: from aserp2120.oracle.com ([141.146.126.78]:42434) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1juHwQ-0007qF-9I for bug-gnu-emacs@gnu.org; Sat, 11 Jul 2020 12:01:31 -0400 Original-Received: from pps.filterd (aserp2120.oracle.com [127.0.0.1]) by aserp2120.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 06BFqk7P112530 for ; Sat, 11 Jul 2020 16:01:28 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-2020-01-29; bh=ZQjNWWpdJQUciRc6gV9QfuQqUlI/Ir/BroktLqGm2bQ=; b=vkF3qTgjWs6zk0u3Wfmi3gjgHTslzO9VrljnO9owl4CiI0aKb+wqW1HSUtHHo/7Bljo6 GMp03VNEbxHKwcSGWVopFgCQerpQc+aLa3F4HPfTJHfunpvIjkWDcMTegw14y6JJbU3x 2SbuxNrEtSTkY/uVJx6Fbq/jWGlNdwlUCCvNeJaDDvv/6LXRsEpPVYq6GHGItjMWSlYf TduDM+GVANLic7CkWYuJfsNIqxFp2mgu7KZjFE6m+ACSzaNYtak1BEiR+h6xMdzVFwj7 8b/Yy9ChM42V2IEYY/529x0/T/2vXprySTtUxhFAo5QFXyOoNX/z5JyCzDWeX20vJtwt Dw== Original-Received: from aserp3030.oracle.com (aserp3030.oracle.com [141.146.126.71]) by aserp2120.oracle.com with ESMTP id 3275cksmt4-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL) for ; Sat, 11 Jul 2020 16:01:28 +0000 Original-Received: from pps.filterd (aserp3030.oracle.com [127.0.0.1]) by aserp3030.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 06BFnPtu196476 for ; Sat, 11 Jul 2020 16:01:28 GMT Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserp3030.oracle.com with ESMTP id 3273fbgtnx-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Sat, 11 Jul 2020 16:01:28 +0000 Original-Received: from abhmp0012.oracle.com (abhmp0012.oracle.com [141.146.116.18]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id 06BG1PpK031077 for ; Sat, 11 Jul 2020 16:01:27 GMT X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.5017.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9679 signatures=668680 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=1 mlxlogscore=935 phishscore=0 spamscore=0 adultscore=0 mlxscore=0 bulkscore=0 malwarescore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2006250000 definitions=main-2007110123 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9679 signatures=668680 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=1 priorityscore=1501 bulkscore=0 adultscore=0 lowpriorityscore=0 phishscore=0 spamscore=0 impostorscore=0 malwarescore=0 mlxlogscore=924 clxscore=1015 mlxscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2006250000 definitions=main-2007110123 Received-SPF: pass client-ip=141.146.126.78; envelope-from=drew.adams@oracle.com; helo=aserp2120.oracle.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/07/11 12:01:29 X-ACL-Warn: Detected OS = Linux 3.1-3.10 [fuzzy] X-Spam_score_int: -63 X-Spam_score: -6.4 X-Spam_bar: ------ X-Spam_report: (-6.4 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H2=-1, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list 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-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:182922 Archived-At: C-h f seq-map ___ seq-map is a compiled Lisp function in 'seq.el'. (seq-map FUNCTION SEQUENCE) Return the result of applying FUNCTION to each element of SEQUENCE. This is a generic function. Implementations: (function (sequence sequence)) in 'seq.el'. Undocumented (function sequence) in 'seq.el'. Undocumented ___ This doc doesn't stand on its own at all, beyond the first line. It doesn't look other Emacs doc strings. It reads like some text generated primitively by computer, with no real care about readers/users. You can't have a clue about what "Implementations:" means, or the individual implementation descriptions mean, unless you know about `cl-defgeneric' and `cl-defmethod'. At the very least there should be some link to the doc of those, or (preferably) a description of what's involved by saying "This is a generic function" - IF that's really necessary to understanding `seq-map'. Elisp users shouldn't be expected to be proficient in Common Lisp. They should be able to use and understand a function such as `seq-map' without caring about its implementation. seq.el constructs should be describable and described on their own, ideally without requiring users to dig into Common Lisp constructs. Or IF understanding the implementation is really necessary, then the fact that seq.el is implemented using cl constructs can't be elided. Is that really the case? What we have now is a pretty useless, and quite confusing, indirect/implicit reference to a cl implementation. Why? How is that helpful? In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32) of 2019-08-29 Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd Windowing system distributor `Microsoft Corp.', version 10.0.18362 Configured using: `configure --without-dbus --host=3Dx86_64-w64-mingw32 --without-compress-install 'CFLAGS=3D-O2 -static -g3''