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#42324: 26.3; Doc string of `seq-concatenate' Date: Tue, 25 Aug 2020 15:46:59 -0700 (PDT) Message-ID: References: Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="14827"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 42324@debbugs.gnu.org To: Stefan Kangas Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Aug 26 00:48:10 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 1kAhje-0003kE-9N for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 26 Aug 2020 00:48:10 +0200 Original-Received: from localhost ([::1]:32886 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kAhjd-0002Va-BE for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 25 Aug 2020 18:48:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:59434) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kAhjW-0002VA-SP for bug-gnu-emacs@gnu.org; Tue, 25 Aug 2020 18:48:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:53062) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kAhjW-0006Z7-J9 for bug-gnu-emacs@gnu.org; Tue, 25 Aug 2020 18:48:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1kAhjW-0002Hz-HQ for bug-gnu-emacs@gnu.org; Tue, 25 Aug 2020 18:48: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, 25 Aug 2020 22:48:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 42324 X-GNU-PR-Package: emacs Original-Received: via spool by 42324-submit@debbugs.gnu.org id=B42324.15983956296919 (code B ref 42324); Tue, 25 Aug 2020 22:48:02 +0000 Original-Received: (at 42324) by debbugs.gnu.org; 25 Aug 2020 22:47:09 +0000 Original-Received: from localhost ([127.0.0.1]:36375 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kAhif-0001nE-8A for submit@debbugs.gnu.org; Tue, 25 Aug 2020 18:47:09 -0400 Original-Received: from userp2130.oracle.com ([156.151.31.86]:41644) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kAhid-0001iT-OY for 42324@debbugs.gnu.org; Tue, 25 Aug 2020 18:47:08 -0400 Original-Received: from pps.filterd (userp2130.oracle.com [127.0.0.1]) by userp2130.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 07PMkIWd152888; Tue, 25 Aug 2020 22:47:01 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2020-01-29; bh=QSZcDX76OqE6DafD0pYg+Onl9a4JMzW+gBZjJ57aIv0=; b=MB9Tqfe6LlGAdfgLU33bkOyiYgEIZglu3hpyC8VyXhQMxGyjFmF9QyieZfZGgNr0+bdT Gszoa2AII20S6nmTirsADNRPuwzNGJTHjVR7mSkZhCQfV0SSJwWhYaKAINLATrfWFpSM m+rArTICfnGaxX/hfLWs5h+zxd4jadR65OJEeTBpvcKG8CUcNoTX8ML7Dz0InFQUWHsv /59uHHCG35RQE8GiqPy/j+3awkqoPVbTUXyUsGvIstvFOkfoBcAlBt/GeklroPKOfPOw zf5DBPgcj4a7jm3TlZ3tOlSemeREJ14E/dLoYw6OPFxq0PC6v7uG12/dGH2AlA40/rTp bA== Original-Received: from userp3030.oracle.com (userp3030.oracle.com [156.151.31.80]) by userp2130.oracle.com with ESMTP id 333csj5c5j-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Tue, 25 Aug 2020 22:47:01 +0000 Original-Received: from pps.filterd (userp3030.oracle.com [127.0.0.1]) by userp3030.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 07PMfIad095272; Tue, 25 Aug 2020 22:47:01 GMT Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by userp3030.oracle.com with ESMTP id 333r9k5h9s-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 25 Aug 2020 22:47:01 +0000 Original-Received: from abhmp0004.oracle.com (abhmp0004.oracle.com [141.146.116.10]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id 07PMl0G2029805; Tue, 25 Aug 2020 22:47:00 GMT In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.5044.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9724 signatures=668679 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 adultscore=0 phishscore=0 suspectscore=0 malwarescore=0 spamscore=0 mlxlogscore=999 mlxscore=0 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2006250000 definitions=main-2008250169 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9724 signatures=668679 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 mlxscore=0 bulkscore=0 clxscore=1011 spamscore=0 priorityscore=1501 impostorscore=0 adultscore=0 lowpriorityscore=0 suspectscore=0 mlxlogscore=999 phishscore=0 malwarescore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2006250000 definitions=main-2008250169 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:186362 Archived-At: > > 1. See bug #42323 for the problem of the unhelpful, implicit reference > > to CL implementations and "generic function". >=20 > Do we need two bugs to track that? It looks to me like essentially the > same issue. Point #1 is common to both bugs, i.e., it's a problem for both doc strings. But #1 is not the only problem for `seq-concatenate'. If you fix #1 in a general way, so it is fixed for both doc strings (and hopefully others), then you can close #42323. But if only #1 is fixed then #42324 isn't fixed. That's why there are 2 bug reports. I don't know how #1 will be fixed, e.g. whether it will be fixed for only this or that doc string or all relevant doc strings. > > 2. The doc of `seq-concatenate' _really_ needs a description of how it > > differs from `cl-concatenate'. That's completely unclear. >=20 > On current master I see: >=20 > cl-concatenate is an alias for =E2=80=98seq-concatenate=E2=80=99 in =E2= =80=98cl-extra.el=E2=80=99. I see. That's not the case in the Emacs version of the bug report. Is that correct? Does `seq-concatenate' correctly implement Common Lisp `concatenate'? If so, then the alias is good. If not, then `cl-concatenate' needs to be fixed to correctly fit the bill. > > 3. The doc says nothing about each SEQUENCE actually being automaticall= y > > converted (by copying, presumably) into a real sequence: > > `seq-into-sequence'. It's not clear what's allowed as SEQUENCE. >=20 > I'm not sure I understand this. In Emacs 26.3, this is the definition of `seq-concatenate': (cl-defgeneric seq-concatenate (type &rest sequences) "Concatenate SEQUENCES into a single sequence of type TYPE. TYPE must be one of following symbols: vector, string or list. \n(fn TYPE SEQUENCE...)" (apply #'cl-concatenate type (seq-map #'seq-into-sequence sequences))) First, in this Emacs version clearly `cl-concatenate' can't be the same as `seq-concatenate'. Second, `seq-into-sequence' seems like a really bad name, for something that either raises an error or is `identity'. The name suggests that something that is not quite a sequence gets converted into a sequence. I was misled by the name, I guess. Well, maybe not. Apparently `cl-defgeneric' just defines _default_ behavior. So the point remains: the doc string should say that the SEQUENCES are first converted into proper sequences (in some way), which are then passed to `cl-concatenate'. And it should probably state the default behavior of just raising an error if not already a sequence. I'd say, overall, that I don't understand the behavior by reading the doc string. And we should. We shouldn't have to guess that `cl-defgeneric' is used, and so the behavior might actually be this, that, or the other thing (or whatever the case may be). The do string should say what the behavior is, including what it _can be_, if `cl-defgeneric' allows it to end up differing, depending on SEQUENCES. > > #2 is the main reason I filed this bug report. What's the difference? > > Why/when would you use one rather than the other?