From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Tomas Hlavaty Newsgroups: gmane.emacs.devel Subject: Re: Declaring Lisp function types Date: Sat, 16 Mar 2024 14:39:24 +0100 Message-ID: <87v85mthwz.fsf@neko.mail-host-address-is-not-set> References: <87y1ajtl2h.fsf@neko.mail-host-address-is-not-set> <86wmq3732h.fsf@gnu.org> 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="6202"; mail-complaints-to="usenet@ciao.gmane.io" Cc: acorallo@gnu.org, emacs-devel@gnu.org, stefankangas@gmail.com To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Mar 16 14:40:10 2024 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 1rlUGg-0001Qg-92 for ged-emacs-devel@m.gmane-mx.org; Sat, 16 Mar 2024 14:40:10 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rlUG5-000615-GX; Sat, 16 Mar 2024 09:39:33 -0400 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 1rlUG3-00060x-42 for emacs-devel@gnu.org; Sat, 16 Mar 2024 09:39:31 -0400 Original-Received: from logand.com ([37.48.87.44]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rlUG1-0001mJ-Gb; Sat, 16 Mar 2024 09:39:30 -0400 Original-Received: by logand.com (Postfix, from userid 1001) id E1EA019E86B; Sat, 16 Mar 2024 14:39:26 +0100 (CET) X-Mailer: emacs 28.2 (via feedmail 11-beta-1 I) In-Reply-To: <86wmq3732h.fsf@gnu.org> Received-SPF: pass client-ip=37.48.87.44; envelope-from=tom@logand.com; helo=logand.com X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, SPF_HELO_PASS=-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:317111 Archived-At: On Fri 15 Mar 2024 at 20:38, Eli Zaretskii wrote: >> all cases are grep-unfriendly > > What do you mean by that? > Please tell more: what would you like to grep for and why? Because good names help working with code bases. (Almost like being given a direct link (like URL) instead of instructions to go that page, click foo then click bar then search for baz...) In the context of "Declaring Lisp function types", grep gives too many false positives when searching for the symbol 'function' or 'type'. Some people suggested more complex regexp to match the declare sexp but that breaks down pretty quickly. A better, more unique symbol name instead of 'function' or 'type' would be much easier to find. Looking at (info "(elisp)Declare Form") there are examples of good and bad names for declare spec properties. Good; try searching for these: (rg "~/mr/emacs" "advertised-calling-convention") (rg "~/mr/emacs" "side-effect-free") (rg "~/mr/emacs" "no-font-lock-keyword") Bad; try searching for these: (rg "~/mr/emacs" "pure") (rg "~/mr/emacs" "speed") Interestingly, the info page above says that the speed property "specifies the value of native-comp-speed in effect for native compilation of this function". If the property was called native-comp-speed, it - would be more correct, - it would be easier to search for, - I could even M-. on the symbol and jump automatically to the definition and see the documentation with minimal effort and distraction, - I would even see helpful text as an eldoc message and see possible values just by placing cursor on the symbol name. etc Try this in elisp-mode: (defun foo (a b) (declare (integer a b) (function a b) (type a b) (speed -1) (native-comp-speed -1) (advertised-calling-convention) (side-effect-free) (no-font-lock-keyword) ) (+ a b 42)) Place your cursor on integer, function, type, speed, native-comp-speed, advertised-calling-convention, side-effect-free, no-font-lock-keyword and watch the difference in eldoc message, try M-. or rgrep emacs codebase etc. The symbol "function" already has specific meaning. Using it as a declare spec property name is just bad. For example, eldoc or M-. shows something unrelated to "Declaring Lisp function types". The other symbols do not show or lead to anything, those are dead-ends magically doing something to the codebase without me being able to use usual tools to understand and navigate them. This gap could be bridged by defining dummy function/macro that would show the right arguments and documentation and also display useful eldoc message. For example like this: (defun side-effect-free (val) "If VAL is non-=E2=80=98nil=E2=80=99, this function is free of side effec= ts, so the byte compiler can ignore calls whose value is ignored. This is the same as the =E2=80=98side-effect-free=E2=80=99 property of t= he function=E2=80=99s symbol, *note Standard Properties::." (error "side-effect-free is not meant to be called")) But maybe it would be possible to structure the code in such a way that this dummy would not be needed, like the case of the symbol "native-comp-speed" (if it was called native-comp-speed instead of speed). Searching for no-font-lock-keyword does not show any declare definition. Is it not used for anything? Elisp has great tools for navigating and understanding code, why work against them? Lisp symbols are a good concept supported by various tools; use them, give them good names and all those tools will work as usual and be very helpful in many contexts.