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: Thu, 9 Nov 2023 13:41:48 +0000 Message-ID: References: <838r7g8pys.fsf@gnu.org> <87bkcbrgnr.fsf@posteo.net> <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="20488"; 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 Thu Nov 09 14:42:47 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 1r15J1-00058r-HG for ged-emacs-devel@m.gmane-mx.org; Thu, 09 Nov 2023 14:42:47 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1r15IN-0005bv-LU; Thu, 09 Nov 2023 08:42:07 -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 1r15IL-0005Tv-Dm for emacs-devel@gnu.org; Thu, 09 Nov 2023 08:42:05 -0500 Original-Received: from mail-lf1-x136.google.com ([2a00:1450:4864:20::136]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1r15II-0000XG-CI for emacs-devel@gnu.org; Thu, 09 Nov 2023 08:42:05 -0500 Original-Received: by mail-lf1-x136.google.com with SMTP id 2adb3069b0e04-507be298d2aso1093856e87.1 for ; Thu, 09 Nov 2023 05:42:02 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1699537320; x=1700142120; 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=KoWpRVc6FvW8A97QfX7chJFMHasiNG58mywPPlY/fBo=; b=gW7f3W/YJQ19FnZCY5/fPQhdUwPGhEf/lUfSfFtTKp2fB8Efe3J0ZnpE3oOVW4vTD6 8nZO9rLWjqyhjECo3uY2375ONOuo8B4zG3oHGgVdSEpxitzRdjVYUbIvQQFKz8nO7SXc Dg+zE+w6KGWHWPorLFYo+Fm5GlKwVh6cXuMLIRtuJTp5fcaEjSJsy0yLO32qizjQ3B9m c7y4RpAaGIaJntLCmqsbHiN+eRIihzXWjYQ3Ln/poUOeCzyyS7x8a4vt5alRi2kpFEla carVfZ76j5J4akH4NX+IGTC6UKsYIcsz7zQmL3+GdtGoaUajJ9mup+zy2/MqaffZqK3g Rktw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1699537320; x=1700142120; 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=KoWpRVc6FvW8A97QfX7chJFMHasiNG58mywPPlY/fBo=; b=eBRJzuFFXp/tKrvvdKGwmgI/WNnVpEwI3qHTRUFUhgdBsG2Xd52H4ISGTRPuwDo8uU BCircTCvVBjmWx6q3t9HVPBU216Ve+/j3Ic/osbU7W4gLFuyq+FC56e8f3InMSeussJI DCgWYLbFcypRX+0XKv8dw+F0xOX2HxEOk2VGDx95ddCboVdvQPQ62k9+fh9Rn3dZbP76 PQjv1fRT7agFpAMnzasAKyCTKPiEs4/tGhSd/6s/t8RFscfg7p9GwWUReHh3+plZK/D2 XbCTF5Dh1JkwcvCBVP1DSKY/k70ZWm4KUhcvFY8hlLVONnLUGmjMS0DF2kAd/9g6p/MH kqdQ== X-Gm-Message-State: AOJu0YyqZ17RbdAlVrKSBvlilfH5qc0UO6JGokxPHqVk0OHjyswsWjFe vWSWFoJWrO2K6EXx0f0lSNPcflAzcMIPVffmvzt6etdJVXs= X-Google-Smtp-Source: AGHT+IGv1qzmg12zp+uXI9P4K9ZQ8UmwZP6wmJ6Wo7BfHgwXEaILkRQSquaI65YdgQqgkbp9nou3UYGyl+CFwbz9qRg= X-Received: by 2002:a05:6512:480b:b0:500:b42f:1830 with SMTP id eo11-20020a056512480b00b00500b42f1830mr1099958lfb.63.1699537319764; Thu, 09 Nov 2023 05:41:59 -0800 (PST) In-Reply-To: Received-SPF: pass client-ip=2a00:1450:4864:20::136; envelope-from=joaotavora@gmail.com; helo=mail-lf1-x136.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:312408 Archived-At: On Thu, Nov 9, 2023 at 1:36=E2=80=AFPM Alan Mackenzie wrote: > > 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 that > > 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 starting > 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 "refers > to" means. > (iv) cl--expr-contains-any; completely undocumented. > (v) cl--expr-depends-p: It's unclear what X and Y are, though Y appears > to be some sort of container of symbols. It's unclear what sort of > "dependency" the function handles, or what "may" means in the context. > > 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. What problem are you trying to solve by enhancing these docstrings? I thou= ght the problem here was code that _used_ cl-lib.el, not hacking on cl-lib.el itself. Jo=C3=A3o