From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: =?UTF-8?B?Sm/Do28gVMOhdm9yYQ==?= Newsgroups: gmane.emacs.devel Subject: Re: What's missing in ELisp that makes people want to use cl-lib? Date: Fri, 10 Nov 2023 12:53:10 +0000 Message-ID: References: <25924.21015.19614.951576@orion.rgrjr.com> <87bkc4jpja.fsf@dataswamp.org> <8a7362da-3cc4-221c-7b8a-a9918677adff@gutov.dev> 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="13247"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Dmitry Gutov , =?UTF-8?Q?Gerd_M=C3=B6llmann?= , =?UTF-8?B?QmrDtnJuIEJpZGFy?= , emacs-devel@gnu.org To: Alan Mackenzie Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Nov 10 13:53:42 2023 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 1r1R13-0003DI-Fe for ged-emacs-devel@m.gmane-mx.org; Fri, 10 Nov 2023 13:53:41 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1r1R0q-0008CS-U0; Fri, 10 Nov 2023 07:53:28 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r1R0p-0008CK-L2 for emacs-devel@gnu.org; Fri, 10 Nov 2023 07:53:27 -0500 Original-Received: from mail-lf1-x12a.google.com ([2a00:1450:4864:20::12a]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1r1R0n-0002Cg-I7 for emacs-devel@gnu.org; Fri, 10 Nov 2023 07:53:27 -0500 Original-Received: by mail-lf1-x12a.google.com with SMTP id 2adb3069b0e04-507be298d2aso2566832e87.1 for ; Fri, 10 Nov 2023 04:53:24 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1699620803; x=1700225603; darn=gnu.org; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=Dn6Ad+jJCoyiv9L9rTbfldZ1y2zPs5V0GTHyKo8cZeA=; b=OAYYhSQeiYDr6FRE1xfKPZkzZF8PnQC+ksjLVhzvROpUiNgeTgcIkxrcYQFyqoBDm1 KDm65JAEWrcxjI+5ZZQ9BvFWsnfbyBQzXOamJ/ubYrTCjtZvUnmcNsHyw2GtRjkFoqyZ bBi04XsfV/QRyuOCSqKCoAUGtPxnfZtxaeq55ASqryX78wbPR7Kxdk9akPBVjpC0KOAD /XTDaMG4nSnEu63MLfyEawlAHZEfF4Bj5xw+w0kIAS69RX0I5gTsM7NYjY4KKOrsT+bX ASZ6WRJXwwYLBRhExG6PonJXt0wsv86SW3CQdoj/y7SJ65eN7UQT/XYGmRLFmGjZAlnN awDA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1699620803; x=1700225603; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=Dn6Ad+jJCoyiv9L9rTbfldZ1y2zPs5V0GTHyKo8cZeA=; b=NR/ZTW5AnjSM8oY3chqrI0p5GG8R/O4Yhkjs6U8cEuNvvt2kUPWDr+65mG1n3BkJXX 6sYjbdGmJL90HoKBiLJPP25GtBte8wMN0hLs5dcX1/ejjmE8vXevhRQarRbpxdszvQlY 5Dz7Go+lzKeHySo8nHhFV17uxekhljgNyTwhJy2YKWFdWAczB+obbTyzCFo85czDyCZW tw1371LKlbRpu1zaKDLqf3/gHEL4b/pYQxydtbZNln4hcjAwGELumrjQUKFab5E2uBwC 2ugEnrakc/uRJT2lyZ4V3oAFAh+B5LgiSIJuPCPr9qV2ef8S2brz4R/TUQxaJz+Kdwz1 TACQ== X-Gm-Message-State: AOJu0Yz4pDRBuXWSOk1zqxxhqO6RZAA77dG+uHJHmaeRL03KxhhHcVBa V5Vr9dH05Red0SIcqtjc8c8r5i/NnUe24+AttSc= X-Google-Smtp-Source: AGHT+IFAVdMxVAYS0k6R6uxOZ5l4P4uEtZpnlBZqWkrkknc/RioEJAR20nUbhWv1tPzPotjePjEe3p2co+CICgZjEDU= X-Received: by 2002:a05:6512:124d:b0:509:4599:12d9 with SMTP id fb13-20020a056512124d00b00509459912d9mr5281087lfb.6.1699620803240; Fri, 10 Nov 2023 04:53:23 -0800 (PST) In-Reply-To: Received-SPF: pass client-ip=2a00:1450:4864:20::12a; envelope-from=joaotavora@gmail.com; helo=mail-lf1-x12a.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 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-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:312482 Archived-At: On Fri, Nov 10, 2023 at 12:13=E2=80=AFPM Alan Mackenzie wrote: > > Hello, Jo=C3=A3o. > > On Thu, Nov 09, 2023 at 13:41:48 +0000, Jo=C3=A3o T=C3=A1vora wrote: > > On Thu, Nov 9, 2023 at 1:36=E2=80=AFPM Alan Mackenzie wrot= e: > > > > Hello, Jo=C3=A3o. > > > > On Thu, Nov 09, 2023 at 12:40:24 +0000, Jo=C3=A3o T=C3=A1vora wrote: > > > > On Thu, Nov 9, 2023 at 11:49=E2=80=AFAM Dmitry Gutov wrote: > > > > > > Improving cl-lib's documentation would be a welcome effort. > > > > > For sure, and not a hard one as well, as all those functions and > > > > macros are pretty good, often flawless emulations of CL functions t= hat > > > > are impeccably documented in > > > > > http://www.lispworks.com/documentation/HyperSpec/Front/ > > > > > Which is of free access (though not of a compatible license, I > > > > think). But if people can point to the 5 most confusing functions > > > > they think are poorly documented, I volunteer to rewrite the > > > > docstrings for them. > > > > How much are you prepared to do? I don't have a list of the _most_ > > > confusing doc strings, there are too many to chose from. But startin= g > > > at the start of cl-macs.el, we have: > > > > (i) cl--compiler-macro-list*; completely undocumented. > > > (ii) cl--simple-expr-p: Talks about "side effects", but not what they > > > are side effects of. Doesn't describe it's parameters or return > > > value. It's unclear what it is that "executes quickly". > > > (iii) cl--expr-contains: It's unclear what X and Y are, and what "ref= ers > > > to" means. > > > (iv) cl--expr-contains-any; completely undocumented. > > > (v) cl--expr-depends-p: It's unclear what X and Y are, though Y appea= rs > > > to be some sort of container of symbols. It's unclear what sort of > > > "dependency" the function handles, or what "may" means in the conte= xt. > > > > There are many more. > > > These are all internal functions and implementation details. They're > > not necessary at all for users of cl-lib.el, only for its developers. > > So, you're not prepared to rewrite their doc strings as you promised > yesterday, any more. I thought the whole problem is that code using cl-lib.el is hard to use. You said cl-labels was "obscure", so I was prepared to enhance its docstring, yes. That's a public macro. Along with 4 other "obscure" public ones. Documentation cl-lib's implementation details is something else entirely. It doesn't hurt if there's suspicion that cl-lib.el is misbehaving in function or efficiency. But that's not the matter in discussion here and it doesn't solve the presumed problem of not understanding code that makes uses cl-lib. > > What problem are you trying to solve by enhancing these docstrings? > Being able to debug Emacs problems. What problem specifically are you having trouble with? What do you ultimately want to achieve that you can't without docstrings for cl-lib.el's implementation details. This might be an XY problem (https://en.wikipedia.org/wiki/XY_problem) > cl-lib uses itself, and needs debugging too. Debugging code that uses > abstractions often requires penetrating these abstractions and checking > their innards. Well, no. I don't go read OS source code whenever I have doubts about how to use a system call or how to read a given piece of code that uses that system call, I read the manual page for the system call itself. Just as I don't pull up a magnifying glass to check if my CPU's transistors are doing what they should, I trust the data sheet describing the instructions. So, no, at least not desirably. That's the whole argument for good docstrings: that it relieves you from having to penetrate innards to understand a function's interface. Feels a bit odd to be defending age-old ideas of encapsulation and information-hiding here. To summarize, I thought it would be absolutely clear that I volunteered to write docstrings for public functions, public interfaces. I'm amazed it wasn't, but I apologize for the misunderstanding nonetheless. Docstrings for things that the user sees, is confused by, finds obscure, etc. Give me 5 of those, and I'll rework their docstrings for clarity. I suggest cl-labels since you singled it out and some sequence manipulating functions which just say: "Keywords supported: :test :test-not :key :start :end :from-end" but don't explain what each of those keyword arguments do. Another useful thing would be to extend eldoc support in Elisp mode to be able to highlight the currently active keyword argument. I'll also look into that, but no promises. Thanks, Jo=C3=A3o