From debbugs-submit-bounces@debbugs.gnu.org Fri Oct 04 08:26:13 2024 Received: (at submit) by debbugs.gnu.org; 4 Oct 2024 12:26:13 +0000 Received: from localhost ([127.0.0.1]:34639 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1swhNs-0002Jz-Sv for submit@debbugs.gnu.org; Fri, 04 Oct 2024 08:26:13 -0400 Received: from lists.gnu.org ([209.51.188.17]:54244) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1swhNr-0002Js-7j for submit@debbugs.gnu.org; Fri, 04 Oct 2024 08:26:11 -0400 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 1swhNn-0001Cs-NJ for bug-gnu-emacs@gnu.org; Fri, 04 Oct 2024 08:26:07 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1swhNn-0002L8-Fa for bug-gnu-emacs@gnu.org; Fri, 04 Oct 2024 08:26:07 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:Subject:To:From:Date:in-reply-to: references; bh=/buNuUFuHBQIrJ7lHXFJ4n6BIxUNHqChaz8ujBW3HTE=; b=YD5NXND8Rfkvqa +82xs3YawKyo/hz7J2XVKyfS4Gt/Afb20Pd/JRDqbdtIm6UypJANV/0lOeuSm1lhdjRp/iN9537Fi RRfBLGmmgq/4rEAx9xbVzZubWmb81xB1Mhw3DcEuV197dDpPMIFhXfu+i1F/4hQegbuD/cnR+WAYz ocLk/EohpHcjEP9IU97rnFGMvblGKJSyGTmdCskC2Bvmx8jRKV/bcVH6JLFZoze07qktv5dDWOpWD AeXE7yS36JUDsbQUY4lHq5ia337Hd1BkV2a690LiDJ0FTZlX7dR4R9HkH/bwC8A4M12bFGVI2AOH5 FlF+cPV5f46MDTB85P5A==; Date: Fri, 04 Oct 2024 15:25:50 +0300 Message-Id: <86msjkxdf5.fsf@gnu.org> From: Eli Zaretskii To: bug-gnu-emacs@gnu.org Subject: 30.0.91; Type specifiers of functions X-Debbugs-Cc: Andrea Corallo MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) To reproduce: emacs -Q C-h f sort-lines RET (That particular function is just an example, basically, any function should do.) Observe in the *Help* buffer: sort-lines is an autoloaded interactive byte-code-function in ‘sort.el’. (sort-lines REVERSE BEG END) If sort.el was native-compiled, you will see this instead: sort-lines is an autoloaded interactive native-comp-function in ‘sort.el’. (sort-lines REVERSE BEG END) So far so good, but in a long-running Emacs session I see this: sort-lines is an autoloaded interactive native-comp-function in ‘sort.el’. (sort-lines REVERSE BEG END) Inferred type: (function (t t t) t) <<<<<<<<<<<<<<<<<<<<<< and sometimes this: bobp is a primitive-function in ‘src/editfns.c’. (bobp) Declared type: (function nil boolean) <<<<<<<<<<<<<<<<<<<<< These Declared/Inferred type thingies are not documented anywhere, AFAICT. If one looks really hard, one can find in "Declare Form" the description of "(ftype TYPE &optional FUNCTION)", but still nothing about declared/inferred. I see in help-fns.el:help-fns--signature that we call comp-function-type-spec to get this information, and the doc string of comp-function-type-spec says: Return the type specifier of FUNCTION. But there are no matches for "type specifier" anywhere in the ELisp manual, and comp-function-type-spec itself is not documented there. Even after looking and finding all those pieces of the puzzle, the overall picture is not clear. The following is missing, and should be documented in the ELisp manual: . what is the importance of inferred vs declared type . how to read the type specifiers, and in particular what do those "t" members mean, and more generally, which forms can appear in the car of the cons cell returned by comp-function-type-spec . why "C-h f" shows this information only for some functions and not for others, and what is the significance of that Bottom line: we decided that this information is important enough to show it in the *Help* buffer, so we should explain its arcane parts to make them useful. In GNU Emacs 30.0.91 (build 26, i686-pc-mingw32) of 2024-10-04 built on ELIZ-PC Windowing system distributor 'Microsoft Corp.', version 10.0.22631 System Description: Microsoft Windows 10 Enterprise (v10.0.2009.22631.4169) Configured using: 'configure -C --prefix=/d/usr --with-wide-int --enable-checking=yes,glyphs --without-native-compilation 'CFLAGS=-O0 -gdwarf-4 -g3'' Configured features: ACL GIF GMP GNUTLS HARFBUZZ JPEG LCMS2 LIBXML2 MODULES NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS TREE_SITTER WEBP XPM ZLIB Important settings: value of $LANG: ENU locale-coding-system: cp1252 Major mode: Lisp Interaction Minor modes in effect: tooltip-mode: t global-eldoc-mode: t eldoc-mode: t show-paren-mode: t electric-indent-mode: t mouse-wheel-mode: t tool-bar-mode: t menu-bar-mode: t file-name-shadow-mode: t global-font-lock-mode: t font-lock-mode: t blink-cursor-mode: t minibuffer-regexp-mode: t line-number-mode: t indent-tabs-mode: t transient-mark-mode: t auto-composition-mode: t auto-encryption-mode: t auto-compression-mode: t Load-path shadows: None found. Features: (shadow mail-extr emacsbug message mailcap yank-media puny dired dired-loaddefs rfc822 mml mml-sec password-cache epa derived epg rfc6068 epg-config gnus-util time-date subr-x mm-decode mm-bodies mm-encode mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail rfc2047 rfc2045 ietf-drums mm-util mail-prsvr mail-utils shortdoc text-property-search comp-common rx sort thingatpt help-fns radix-tree help-mode cl-loaddefs cl-lib rmc iso-transl tooltip cconv eldoc paren electric uniquify ediff-hook vc-hooks lisp-float-type elisp-mode mwheel touch-screen dos-w32 ls-lisp disp-table term/w32-win w32-win w32-vars term/common-win tool-bar dnd fontset image regexp-opt fringe tabulated-list replace newcomment text-mode lisp-mode prog-mode register page tab-bar menu-bar rfn-eshadow isearch easymenu timer select scroll-bar mouse jit-lock font-lock syntax font-core term/tty-colors frame minibuffer nadvice seq simple cl-generic indonesian philippine cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech european ethiopic indian cyrillic chinese composite emoji-zwj charscript charprop case-table epa-hook jka-cmpr-hook help abbrev obarray oclosure cl-preloaded button loaddefs theme-loaddefs faces cus-face macroexp files window text-properties overlay sha1 md5 base64 format env code-pages mule custom widget keymap hashtable-print-readable backquote threads w32notify w32 lcms2 multi-tty move-toolbar make-network-process emacs) Memory information: ((conses 16 62131 14624) (symbols 48 7053 0) (strings 16 20202 2856) (string-bytes 1 391879) (vectors 16 10151) (vector-slots 8 115928 8847) (floats 8 79 4) (intervals 40 346 149) (buffers 896 11)) From debbugs-submit-bounces@debbugs.gnu.org Sat Oct 19 03:01:49 2024 Received: (at 73626) by debbugs.gnu.org; 19 Oct 2024 07:01:49 +0000 Received: from localhost ([127.0.0.1]:41072 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1t23TB-0006wn-4O for submit@debbugs.gnu.org; Sat, 19 Oct 2024 03:01:49 -0400 Received: from eggs.gnu.org ([209.51.188.92]:47604) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1t23T9-0006wW-Am for 73626@debbugs.gnu.org; Sat, 19 Oct 2024 03:01:47 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1t23Sg-0000rl-LK for 73626@debbugs.gnu.org; Sat, 19 Oct 2024 03:01:18 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=NOcspJIQCmT9rZMZdKftxTxERWdy/3ZphNq+WipJmG0=; b=W67joeAvvYAlx3GnA2MP wz4Jto4EqIXtnhvQf+3y2cNKfyfewjr1udBbaBPPxVc3GW28oe0Hw1Xss6mjiGwevFKKBwnGRuyAc YYXGocnJ9pWD2g1DQFfyfoQlmPn+kypOCgSYBDaDKJ9Pt8rIC1DMcFrHGMXRBLgmQ4RQi+uz4elRV sAEZhQQlMgsor8nMmXykl8+GJ4Fs5XBzhZ0jF8LxQNDHAPf3O+ZLEson9KGx/tNPA0eBVfaYc8+eS fRWQyoJ+MBn5DM9RAKo65L/QGNMNlZoc74u1RYe7KNYZ35weGSCZFAAZm9MeUc1xDuhMlAoPkYj8B inUg4rpsMMOF3Q==; Date: Sat, 19 Oct 2024 10:01:15 +0300 Message-Id: <867ca4mv9g.fsf@gnu.org> From: Eli Zaretskii To: Andrea Corallo In-Reply-To: <86msjkxdf5.fsf@gnu.org> (message from Eli Zaretskii on Fri, 04 Oct 2024 15:25:50 +0300) Subject: Re: bug#73626: 30.0.91; Type specifiers of functions References: <86msjkxdf5.fsf@gnu.org> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 73626 Cc: 73626@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Ping! > Cc: Andrea Corallo > Date: Fri, 04 Oct 2024 15:25:50 +0300 > From: Eli Zaretskii > > To reproduce: > > emacs -Q > C-h f sort-lines RET > > (That particular function is just an example, basically, any function > should do.) > > Observe in the *Help* buffer: > > sort-lines is an autoloaded interactive byte-code-function in > ‘sort.el’. > > (sort-lines REVERSE BEG END) > > If sort.el was native-compiled, you will see this instead: > > sort-lines is an autoloaded interactive native-comp-function in > ‘sort.el’. > > (sort-lines REVERSE BEG END) > > So far so good, but in a long-running Emacs session I see this: > > sort-lines is an autoloaded interactive native-comp-function in > ‘sort.el’. > > (sort-lines REVERSE BEG END) > > Inferred type: (function (t t t) t) <<<<<<<<<<<<<<<<<<<<<< > > and sometimes this: > > bobp is a primitive-function in ‘src/editfns.c’. > > (bobp) > > Declared type: (function nil boolean) <<<<<<<<<<<<<<<<<<<<< > > These Declared/Inferred type thingies are not documented anywhere, > AFAICT. If one looks really hard, one can find in "Declare Form" the > description of "(ftype TYPE &optional FUNCTION)", but still nothing > about declared/inferred. I see in help-fns.el:help-fns--signature > that we call comp-function-type-spec to get this information, and the > doc string of comp-function-type-spec says: > > Return the type specifier of FUNCTION. > > But there are no matches for "type specifier" anywhere in the ELisp > manual, and comp-function-type-spec itself is not documented there. > > Even after looking and finding all those pieces of the puzzle, the > overall picture is not clear. The following is missing, and should be > documented in the ELisp manual: > > . what is the importance of inferred vs declared type > . how to read the type specifiers, and in particular what do those > "t" members mean, and more generally, which forms can appear in the > car of the cons cell returned by comp-function-type-spec > . why "C-h f" shows this information only for some functions and not > for others, and what is the significance of that > > Bottom line: we decided that this information is important enough to > show it in the *Help* buffer, so we should explain its arcane parts to > make them useful. > > In GNU Emacs 30.0.91 (build 26, i686-pc-mingw32) of 2024-10-04 built on > ELIZ-PC > Windowing system distributor 'Microsoft Corp.', version 10.0.22631 > System Description: Microsoft Windows 10 Enterprise (v10.0.2009.22631.4169) > > Configured using: > 'configure -C --prefix=/d/usr --with-wide-int > --enable-checking=yes,glyphs --without-native-compilation 'CFLAGS=-O0 > -gdwarf-4 -g3'' > > Configured features: > ACL GIF GMP GNUTLS HARFBUZZ JPEG LCMS2 LIBXML2 MODULES NOTIFY W32NOTIFY > PDUMPER PNG RSVG SOUND SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS > TREE_SITTER WEBP XPM ZLIB > > Important settings: > value of $LANG: ENU > locale-coding-system: cp1252 > > Major mode: Lisp Interaction > > Minor modes in effect: > tooltip-mode: t > global-eldoc-mode: t > eldoc-mode: t > show-paren-mode: t > electric-indent-mode: t > mouse-wheel-mode: t > tool-bar-mode: t > menu-bar-mode: t > file-name-shadow-mode: t > global-font-lock-mode: t > font-lock-mode: t > blink-cursor-mode: t > minibuffer-regexp-mode: t > line-number-mode: t > indent-tabs-mode: t > transient-mark-mode: t > auto-composition-mode: t > auto-encryption-mode: t > auto-compression-mode: t > > Load-path shadows: > None found. > > Features: > (shadow mail-extr emacsbug message mailcap yank-media puny dired > dired-loaddefs rfc822 mml mml-sec password-cache epa derived epg rfc6068 > epg-config gnus-util time-date subr-x mm-decode mm-bodies mm-encode > mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail rfc2047 > rfc2045 ietf-drums mm-util mail-prsvr mail-utils shortdoc > text-property-search comp-common rx sort thingatpt help-fns radix-tree > help-mode cl-loaddefs cl-lib rmc iso-transl tooltip cconv eldoc paren > electric uniquify ediff-hook vc-hooks lisp-float-type elisp-mode mwheel > touch-screen dos-w32 ls-lisp disp-table term/w32-win w32-win w32-vars > term/common-win tool-bar dnd fontset image regexp-opt fringe > tabulated-list replace newcomment text-mode lisp-mode prog-mode register > page tab-bar menu-bar rfn-eshadow isearch easymenu timer select > scroll-bar mouse jit-lock font-lock syntax font-core term/tty-colors > frame minibuffer nadvice seq simple cl-generic indonesian philippine > cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao > korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech > european ethiopic indian cyrillic chinese composite emoji-zwj charscript > charprop case-table epa-hook jka-cmpr-hook help abbrev obarray oclosure > cl-preloaded button loaddefs theme-loaddefs faces cus-face macroexp > files window text-properties overlay sha1 md5 base64 format env > code-pages mule custom widget keymap hashtable-print-readable backquote > threads w32notify w32 lcms2 multi-tty move-toolbar make-network-process > emacs) > > Memory information: > ((conses 16 62131 14624) (symbols 48 7053 0) (strings 16 20202 2856) > (string-bytes 1 391879) (vectors 16 10151) > (vector-slots 8 115928 8847) (floats 8 79 4) (intervals 40 346 149) > (buffers 896 11)) > > > > From debbugs-submit-bounces@debbugs.gnu.org Wed Oct 23 18:29:47 2024 Received: (at 73626) by debbugs.gnu.org; 23 Oct 2024 22:29:47 +0000 Received: from localhost ([127.0.0.1]:32809 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1t3jrO-0003rC-QA for submit@debbugs.gnu.org; Wed, 23 Oct 2024 18:29:47 -0400 Received: from eggs.gnu.org ([209.51.188.92]:56900) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1t3jrL-0003qu-Tn for 73626@debbugs.gnu.org; Wed, 23 Oct 2024 18:29:45 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1t3jqm-0006zP-QI for 73626@debbugs.gnu.org; Wed, 23 Oct 2024 18:29:08 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=trmSfgQIX4P5xzp92ILJZTkuA7mUvK/MLIuYHgdqXw8=; b=AUPpPchq+j9H/+tNbi4W v8Dx+jisakf/dj8vaeYSYz2/oTrZ7srp3pO8+MPtgsP/YeqvCBrqGW3ZLugJc5yCYWXu0dQTqtiSi CGAGH5DUq5bHIsWWMAUapg0UNKKC2fIkxDDItnBHhZcZQdig4XhCFPhbxIdyRtkwKTZjoWgNknuo6 +weR1nFwJ59G7JGARVy9eo2VwKhzDAJ7HYmsdmmCLkS6o8BxoU2FWIkoRIE55sclWW8Z5tsnTN5VQ JTygS8uyUUgc7AcPNHJGrhu09p2QfwA4/RmrkrwckRJKiqDOpGi1DFqLLoSuXIJe7vtODh2U3Apcz VKJrTGWt/l8/HQ==; Received: from acorallo by fencepost.gnu.org with local (Exim 4.90_1) (envelope-from ) id 1t3jqk-0002ia-AC; Wed, 23 Oct 2024 18:29:07 -0400 From: Andrea Corallo To: Eli Zaretskii Subject: Re: bug#73626: 30.0.91; Type specifiers of functions In-Reply-To: <86msjkxdf5.fsf@gnu.org> (Eli Zaretskii's message of "Fri, 04 Oct 2024 15:25:50 +0300") References: <86msjkxdf5.fsf@gnu.org> Date: Wed, 23 Oct 2024 18:29:06 -0400 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 73626 Cc: 73626@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Hi Eli, sorry for being late on this. Eli Zaretskii writes: > To reproduce: > > emacs -Q > C-h f sort-lines RET > > (That particular function is just an example, basically, any function > should do.) > > Observe in the *Help* buffer: > > sort-lines is an autoloaded interactive byte-code-function in > =E2=80=98sort.el=E2=80=99. > > (sort-lines REVERSE BEG END) > > If sort.el was native-compiled, you will see this instead: > > sort-lines is an autoloaded interactive native-comp-function in > =E2=80=98sort.el=E2=80=99. > > (sort-lines REVERSE BEG END) > > So far so good, but in a long-running Emacs session I see this: > > sort-lines is an autoloaded interactive native-comp-function in > =E2=80=98sort.el=E2=80=99. > > (sort-lines REVERSE BEG END) > > Inferred type: (function (t t t) t) <<<<<<<<<<<<<<<<<<<<<< > > and sometimes this: > > bobp is a primitive-function in =E2=80=98src/editfns.c=E2=80=99. > > (bobp) > > Declared type: (function nil boolean) <<<<<<<<<<<<<<<<<<<<< > > These Declared/Inferred type thingies are not documented anywhere, > AFAICT. If one looks really hard, one can find in "Declare Form" the > description of "(ftype TYPE &optional FUNCTION)", but still nothing > about declared/inferred. I see in help-fns.el:help-fns--signature > that we call comp-function-type-spec to get this information, and the > doc string of comp-function-type-spec says: > > Return the type specifier of FUNCTION. > > But there are no matches for "type specifier" anywhere in the ELisp > manual, and comp-function-type-spec itself is not documented there. > > Even after looking and finding all those pieces of the puzzle, the > overall picture is not clear. The following is missing, and should be > documented in the ELisp manual: > > . what is the importance of inferred vs declared type The user get to know that the function type was computed by the compiler or manually declared by the user. > . how to read the type specifiers, The format is the same described for type declarations ((elisp)Top > Functions > Declare Form). I agree we should probably better document this somewhere else, probably in Lisp Data Types? > and in particular what do those "t" members mean, t is a type documented (elisp)Top > Lisp Data Types > Type Hierarchy > and more generally, which forms can appear in the > car of the cons cell returned by comp-function-type-spec Hope I answered before. > . why "C-h f" shows this information only for some functions and not > for others, and what is the significance of that C-h f does not show the inferred type if the functions has still to be native compiled and loaded, the reason is simply that is the native compiler computing the type. > Bottom line: we decided that this information is important enough to > show it in the *Help* buffer, so we should explain its arcane parts to > make them useful. Agree. Is '(elisp)Top > Lisp Data Types' a reasonable place for that? Otherwise where should we do it? Thanks Andrea From debbugs-submit-bounces@debbugs.gnu.org Thu Oct 24 11:48:28 2024 Received: (at 73626) by debbugs.gnu.org; 24 Oct 2024 15:48:28 +0000 Received: from localhost ([127.0.0.1]:35953 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1t404Z-0002J8-PV for submit@debbugs.gnu.org; Thu, 24 Oct 2024 11:48:28 -0400 Received: from eggs.gnu.org ([209.51.188.92]:40406) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1t404Y-0002Il-BD for 73626@debbugs.gnu.org; Thu, 24 Oct 2024 11:48:26 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1t403y-0002eS-9a for 73626@debbugs.gnu.org; Thu, 24 Oct 2024 11:47:50 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=A669EGlip4waHMAyUik7Isnk1453P8LxU7JhndaPKzM=; b=f9NHHVKBPlKf DOIiiVIaqAkDTdIQnOhoF8Htn0Lvf4wrV900lHuoTmKnqGW0lITlnYqxQ5NeNdKujb0bFjVm9OPeE w4Ih2XeLeXAAFY13IU5Np44UlyG8lkuV5DmJbLTFNcnwDX61Z/OuLIfu9hmTCVNdt1hpVmos9JHSw cuTM21EInxIH/wrwYJsftIRlCGjgf/wr+CeVSN1OBiLpXJ9ytKpvoPyk8Ysvo9uaE9IE5Uk8ew157 Kaz7NcbhFp6yr8o2P9Z6u70HA5NOVF5pInURBhB9rRtKhGXDoRV+BLuQlJ/lzIzPC0GvSjbcn7jJi 82QjqIeh9Jly1TmFQtSyDw==; Date: Thu, 24 Oct 2024 18:47:46 +0300 Message-Id: <86ikthcxjx.fsf@gnu.org> From: Eli Zaretskii To: Andrea Corallo In-Reply-To: (message from Andrea Corallo on Wed, 23 Oct 2024 18:29:06 -0400) Subject: Re: bug#73626: 30.0.91; Type specifiers of functions References: <86msjkxdf5.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 73626 Cc: 73626@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Andrea Corallo > Cc: 73626@debbugs.gnu.org > Date: Wed, 23 Oct 2024 18:29:06 -0400 > > Hi Eli, > > sorry for being late on this. No sweat. > > . what is the importance of inferred vs declared type > > The user get to know that the function type was computed by the compiler > or manually declared by the user. And why is that important? > > . how to read the type specifiers, > > The format is the same described for type declarations ((elisp)Top > > Functions > Declare Form). OK, but the relation of that to what we show in the *Help* buffers is not obvious. > I agree we should probably better document this somewhere else, probably > in Lisp Data Types? We need first mention this in "(emacs)Name Help", with a cross-reference to wherever we describe that in the ELisp manual. I tend to think that the main place where this is described in ELisp manual is somewhere in Lisp data Types, perhaps in Type Hierarchy. > > . why "C-h f" shows this information only for some functions and not > > for others, and what is the significance of that > > C-h f does not show the inferred type if the functions has still to be > native compiled and loaded, the reason is simply that is the native > compiler computing the type. This should also be documented in "Name Help", I think. > > Bottom line: we decided that this information is important enough to > > show it in the *Help* buffer, so we should explain its arcane parts to > > make them useful. > > Agree. Is '(elisp)Top > Lisp Data Types' a reasonable place for that? Yes, I think so. Thanks. From debbugs-submit-bounces@debbugs.gnu.org Fri Oct 25 05:36:12 2024 Received: (at 73626) by debbugs.gnu.org; 25 Oct 2024 09:36:12 +0000 Received: from localhost ([127.0.0.1]:37268 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1t4Gjs-0001lm-0W for submit@debbugs.gnu.org; Fri, 25 Oct 2024 05:36:12 -0400 Received: from eggs.gnu.org ([209.51.188.92]:47428) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1t4Gjp-0001lW-Kt for 73626@debbugs.gnu.org; Fri, 25 Oct 2024 05:36:10 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1t4GjE-0002sQ-CR for 73626@debbugs.gnu.org; Fri, 25 Oct 2024 05:35:32 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=WmplOQgQV/Llgq5mJeyovoNCnoHU+G5Ki0pnqHAwp4w=; b=cV6OnF8mJjM6H4zlsgh3 T6R9udsXw3TD65NyY0QfLhQoyzfQa8YS7cPRMRoRVqM7BIFoTIqg19Jc+0gmiz3z7RQ1JqS3ohihN XZI8NuvJNXEIaqzJx/Kot8yOkta6H358q4X7qjJOg3IkdUtA7D8qkIC2IFlYWjL1jqwGNKrVwKCBj t/GFpxCW+vMMrgUsQLrRtTX8l4Qn7qvWBhAKl75l+39BdlKCaVHnPVTiXui5f6PxOpzAWuqCc/Evt Nm04rX9qJ9EMTGj1WiN7hCNyteu6+xQx9Vc8WMmULljSYsXRguOik3q93zlEkPbuvOexcBctk76CA B2DTGJkUXKAjRg==; Received: from acorallo by fencepost.gnu.org with local (Exim 4.90_1) (envelope-from ) id 1t4GjC-0008Bg-Ig; Fri, 25 Oct 2024 05:35:31 -0400 From: Andrea Corallo To: Eli Zaretskii Subject: Re: bug#73626: 30.0.91; Type specifiers of functions In-Reply-To: <86ikthcxjx.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 24 Oct 2024 18:47:46 +0300") References: <86msjkxdf5.fsf@gnu.org> <86ikthcxjx.fsf@gnu.org> Date: Fri, 25 Oct 2024 05:35:30 -0400 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 73626 Cc: 73626@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Eli Zaretskii writes: >> From: Andrea Corallo >> Cc: 73626@debbugs.gnu.org >> Date: Wed, 23 Oct 2024 18:29:06 -0400 >> >> Hi Eli, >> >> sorry for being late on this. > > No sweat. > >> > . what is the importance of inferred vs declared type >> >> The user get to know that the function type was computed by the compiler >> or manually declared by the user. > > And why is that important? I think might be informative for the user to know if the interface was intentionally declared by the programmer or just inferred by the compiler. Of course this my evaluation is somehow subjective. >> > . how to read the type specifiers, >> >> The format is the same described for type declarations ((elisp)Top > >> Functions > Declare Form). > > OK, but the relation of that to what we show in the *Help* buffers is > not obvious. Agree. >> I agree we should probably better document this somewhere else, probably >> in Lisp Data Types? > > We need first mention this in "(emacs)Name Help", with a > cross-reference to wherever we describe that in the ELisp manual. I > tend to think that the main place where this is described in ELisp > manual is somewhere in Lisp data Types, perhaps in Type Hierarchy. > >> > . why "C-h f" shows this information only for some functions and not >> > for others, and what is the significance of that >> >> C-h f does not show the inferred type if the functions has still to be >> native compiled and loaded, the reason is simply that is the native >> compiler computing the type. > > This should also be documented in "Name Help", I think. > >> > Bottom line: we decided that this information is important enough to >> > show it in the *Help* buffer, so we should explain its arcane parts to >> > make them useful. >> >> Agree. Is '(elisp)Top > Lisp Data Types' a reasonable place for that? > > Yes, I think so. Ok gonna work on this. Andrea From debbugs-submit-bounces@debbugs.gnu.org Fri Oct 25 06:20:25 2024 Received: (at 73626) by debbugs.gnu.org; 25 Oct 2024 10:20:25 +0000 Received: from localhost ([127.0.0.1]:37427 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1t4HQe-0003nw-Vn for submit@debbugs.gnu.org; Fri, 25 Oct 2024 06:20:25 -0400 Received: from eggs.gnu.org ([209.51.188.92]:60380) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1t4HQd-0003nk-4a for 73626@debbugs.gnu.org; Fri, 25 Oct 2024 06:20:23 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1t4HPz-0008TG-SF for 73626@debbugs.gnu.org; Fri, 25 Oct 2024 06:19:46 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=4F8f0yHNBD0V6iuSB/PMb5ny+u8xkwQjntlrSvrzSRo=; b=GUo6qqH8dWch 2NPIe0Qi/coqoBajPu0NoFYUwRvbM1Z7UaL5ODaap4OQYLIQcczS8YgjGv+ns4bPY00ylPvquQEMi j4WHFDFhaW2UWvrav7j1E2uTboA+efXYRKh05CzrAoKJW36x8yRWKhXjrcUaGq2atjp0osG/PNf9j vyBGjx8iGVIhnu0niaiE+AlomYSlR+Z1dgTyCjLWzW+aB/n5SMVeVdpH2Oc9Pt2R//WxLBt7Nqunr 1Yr6/yZNXo2lmwkoJTJ8NdhhtuhyhXFcyX8kNWpTvj+SeqQhpNGyBXuwo9HIdeXUwL/AgcSbREfl5 3JNh838YsvFOGesAxxzNeA==; Date: Fri, 25 Oct 2024 13:19:41 +0300 Message-Id: <86seskbi2q.fsf@gnu.org> From: Eli Zaretskii To: Andrea Corallo In-Reply-To: (message from Andrea Corallo on Fri, 25 Oct 2024 05:35:30 -0400) Subject: Re: bug#73626: 30.0.91; Type specifiers of functions References: <86msjkxdf5.fsf@gnu.org> <86ikthcxjx.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 73626 Cc: 73626@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Andrea Corallo > Cc: 73626@debbugs.gnu.org > Date: Fri, 25 Oct 2024 05:35:30 -0400 > > Eli Zaretskii writes: > > >> > Bottom line: we decided that this information is important enough to > >> > show it in the *Help* buffer, so we should explain its arcane parts to > >> > make them useful. > >> > >> Agree. Is '(elisp)Top > Lisp Data Types' a reasonable place for that? > > > > Yes, I think so. > > Ok gonna work on this. Thanks! From debbugs-submit-bounces@debbugs.gnu.org Sat Nov 09 04:13:42 2024 Received: (at 73626) by debbugs.gnu.org; 9 Nov 2024 09:13:42 +0000 Received: from localhost ([127.0.0.1]:53402 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1t9hXJ-0001O6-UY for submit@debbugs.gnu.org; Sat, 09 Nov 2024 04:13:42 -0500 Received: from eggs.gnu.org ([209.51.188.92]:33296) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1t9hXH-0001Nr-O7 for 73626@debbugs.gnu.org; Sat, 09 Nov 2024 04:13:40 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1t9hXC-0001Zg-IY for 73626@debbugs.gnu.org; Sat, 09 Nov 2024 04:13:34 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=1F6Os6f+EgLDYgtF1FW6ROrfWe1kC7gvOBsncdIuPuY=; b=qR8Mz5ez92KH 02UPNb1mZ8FKKYpOdU61inzaFa+UYoqKthbT2q8sB5yF4YVrpldqUu2xA9XqYqQAyMeYgytBO0tco agqfThE3KLHeqLBcp2iaqbGdBHoQM6oSNvoz/PVIpWWfGnHDMPySgIBorlcFdELGnhTJH3Uc2LIUY UHEGCKiUT7f81wL4rMUr4Adk3SRppI35m8tvPXLLQanftZjG9DaPJEWWf2esV77ZeuI8dhp3uYUij PDEW3dpcpqVCS9W1mlFRfsFdhiQ40f8bZdvT/whyUl5SOyFj/N+z2CzY9d57+E89sO3Li8u9hEUxl WP0Lx4cYWNqKaiMKf0j5UA==; Date: Sat, 09 Nov 2024 11:13:31 +0200 Message-Id: <86zfm8n51g.fsf@gnu.org> From: Eli Zaretskii To: acorallo@gnu.org In-Reply-To: <86seskbi2q.fsf@gnu.org> (message from Eli Zaretskii on Fri, 25 Oct 2024 13:19:41 +0300) Subject: Re: bug#73626: 30.0.91; Type specifiers of functions References: <86msjkxdf5.fsf@gnu.org> <86ikthcxjx.fsf@gnu.org> <86seskbi2q.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 73626 Cc: 73626@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > Cc: 73626@debbugs.gnu.org > Date: Fri, 25 Oct 2024 13:19:41 +0300 > From: Eli Zaretskii > > > From: Andrea Corallo > > Cc: 73626@debbugs.gnu.org > > Date: Fri, 25 Oct 2024 05:35:30 -0400 > > > > Eli Zaretskii writes: > > > > >> > Bottom line: we decided that this information is important enough to > > >> > show it in the *Help* buffer, so we should explain its arcane parts to > > >> > make them useful. > > >> > > >> Agree. Is '(elisp)Top > Lisp Data Types' a reasonable place for that? > > > > > > Yes, I think so. > > > > Ok gonna work on this. > > Thanks! Did you have a chance to work on this? From debbugs-submit-bounces@debbugs.gnu.org Tue Nov 12 14:17:34 2024 Received: (at 73626) by debbugs.gnu.org; 12 Nov 2024 19:17:34 +0000 Received: from localhost ([127.0.0.1]:39538 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tAwOL-00080F-Md for submit@debbugs.gnu.org; Tue, 12 Nov 2024 14:17:33 -0500 Received: from eggs.gnu.org ([209.51.188.92]:42338) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tAwOK-000800-28 for 73626@debbugs.gnu.org; Tue, 12 Nov 2024 14:17:32 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tAwOE-0000Rs-90 for 73626@debbugs.gnu.org; Tue, 12 Nov 2024 14:17:26 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=CQwOc+3hF3C/IxGycmidFEck1d7zO6oyjSs2r4JgqWo=; b=dVsLpKly9ZnifjCcAxcO rzos+p5rhnKT2HRmKTKvA2/qDV10D4Z5LWvWvQtwN0gf5QTg1JwFQI39ZfjTLbhFGH3uaM4ziLwhm +vHodoK9R//p2aviW30pPsYevLz3CLdXYVz2xz3l1aM5F//BMePMiXbt5R3tCwtT39aG3Z5mM2YJ+ mnpOa9Cz/6jqAegzrRgMkQH50vgTqkjRynHwqvI2jy0AJhXPOzga9MnYqsSZ/NzfIlUxEZDuvBG/p AP50Ev/pV6v8KLJ6YM7yim5BJ7CP8M1CTLx1uVueduV9WHox2jwIxn+LMdPzlmLyifwFvQmjNSYqA C+SBhjcpMJG50w==; Received: from acorallo by fencepost.gnu.org with local (Exim 4.90_1) (envelope-from ) id 1tAwOC-0001nc-Pz; Tue, 12 Nov 2024 14:17:25 -0500 From: Andrea Corallo To: Eli Zaretskii Subject: Re: bug#73626: 30.0.91; Type specifiers of functions In-Reply-To: <86zfm8n51g.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 09 Nov 2024 11:13:31 +0200") References: <86msjkxdf5.fsf@gnu.org> <86ikthcxjx.fsf@gnu.org> <86seskbi2q.fsf@gnu.org> <86zfm8n51g.fsf@gnu.org> Date: Tue, 12 Nov 2024 14:17:24 -0500 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 73626 Cc: 73626@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Eli Zaretskii writes: >> Cc: 73626@debbugs.gnu.org >> Date: Fri, 25 Oct 2024 13:19:41 +0300 >> From: Eli Zaretskii >> >> > From: Andrea Corallo >> > Cc: 73626@debbugs.gnu.org >> > Date: Fri, 25 Oct 2024 05:35:30 -0400 >> > >> > Eli Zaretskii writes: >> > >> > >> > Bottom line: we decided that this information is important enough to >> > >> > show it in the *Help* buffer, so we should explain its arcane parts to >> > >> > make them useful. >> > >> >> > >> Agree. Is '(elisp)Top > Lisp Data Types' a reasonable place for that? >> > > >> > > Yes, I think so. >> > >> > Ok gonna work on this. >> >> Thanks! > > Did you have a chance to work on this? Not so far sorry, it's on top of my todo list tho. Andrea From debbugs-submit-bounces@debbugs.gnu.org Wed Nov 13 19:28:00 2024 Received: (at 73626) by debbugs.gnu.org; 14 Nov 2024 00:28:00 +0000 Received: from localhost ([127.0.0.1]:44169 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tBNiJ-0003VZ-Pl for submit@debbugs.gnu.org; Wed, 13 Nov 2024 19:28:00 -0500 Received: from eggs.gnu.org ([209.51.188.92]:58750) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tBNiI-0003VN-BE for 73626@debbugs.gnu.org; Wed, 13 Nov 2024 19:27:59 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tBNiD-0000hy-3T for 73626@debbugs.gnu.org; Wed, 13 Nov 2024 19:27:53 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=VRw+wulyG30+vCyZoqHnKUR4xSVtlZgR4fcB/q1PK8U=; b=ALLkq3fvW3HBayFiFz1B plyqHVqzuXCJvwJTrUjgebAMGr403HtpO+3ag6WCb1VWDi525LMEtSEBKoMN0vWD7v+LzBHAaEHoM Ph7uts9BwpXxkSa2NpjzQBEuSy34ngjIkK+JRTVyY/ldowoTpeuxj3KJ3z8mNISFKdrMo/HOUOtcE 6sArVsfNFUbot5KVSDzRBCdhCxf2W8TXIsasqwZv20LOR74Ml0jByU8Zbceq5dJRuNR0W5cfzIWTx cJ4hhHK1UDgPNyeiwUi3CGzfJfDmpImleLRQOIDF+rx0I0WddBxo4H91nki5dIUQ6RmjNy4MTovw2 iZC0jKImifR1LQ==; Received: from acorallo by fencepost.gnu.org with local (Exim 4.90_1) (envelope-from ) id 1tBNiC-00014L-CZ; Wed, 13 Nov 2024 19:27:52 -0500 From: Andrea Corallo To: Eli Zaretskii Subject: Re: bug#73626: 30.0.91; Type specifiers of functions In-Reply-To: (Andrea Corallo's message of "Tue, 12 Nov 2024 14:17:24 -0500") References: <86msjkxdf5.fsf@gnu.org> <86ikthcxjx.fsf@gnu.org> <86seskbi2q.fsf@gnu.org> <86zfm8n51g.fsf@gnu.org> Date: Wed, 13 Nov 2024 19:27:52 -0500 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 73626 Cc: 73626@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) --=-=-= Content-Type: text/plain Andrea Corallo writes: > Eli Zaretskii writes: > >>> Cc: 73626@debbugs.gnu.org >>> Date: Fri, 25 Oct 2024 13:19:41 +0300 >>> From: Eli Zaretskii >>> >>> > From: Andrea Corallo >>> > Cc: 73626@debbugs.gnu.org >>> > Date: Fri, 25 Oct 2024 05:35:30 -0400 >>> > >>> > Eli Zaretskii writes: >>> > >>> > >> > Bottom line: we decided that this information is important enough to >>> > >> > show it in the *Help* buffer, so we should explain its arcane parts to >>> > >> > make them useful. >>> > >> >>> > >> Agree. Is '(elisp)Top > Lisp Data Types' a reasonable place for that? >>> > > >>> > > Yes, I think so. >>> > >>> > Ok gonna work on this. >>> >>> Thanks! >> >> Did you have a chance to work on this? > > Not so far sorry, it's on top of my todo list tho. > > Andrea Okay this is what I'm working on. I felt the need to add a more general '(elisp)Type Specifiers' node as this was never documented and I think deserves its own space. I referenced it from '(emacs)Name Help' where I mentioned we report function type specifiers. Also I could reference it from '(elisp) Declare Form' so that the concept of type specifier (there already mentioned) is explained. There are some mentions of type specifiers in cl.texi which I guess I'll add some xref as well. WDYT? Andrea --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=ts.patch diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index f15b4c5e89d..0f85ff0c832 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -322,6 +322,13 @@ Name Help yet further information is often reachable by clicking or typing @key{RET} on emphasized parts of the text. +The function type, if known, is expressed with a function type specifier +(@pxref{Type Specifiers,,,elisp, The Emacs Lisp Reference Manual}), it +will be specified if the type was manually declared by the programmer or +inferred by the compiler. Note that function type inference works only +when native compilation is enabled (@pxref{native compilation,,, elisp, +The Emacs Lisp Reference Manual}). + @vindex help-enable-symbol-autoload If you request help for an autoloaded function whose @code{autoload} form (@pxref{Autoload,,, elisp, The Emacs Lisp Reference Manual}) diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index bf80a21ee9f..c6953cdd25a 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -2733,7 +2733,7 @@ Declare Form generation and for deriving more precisely the type of other functions without type declaration. -@var{type} is a type specifier in the form @w{@code{(function +@var{type} is a @ref{Type Specifier} in the form @w{@code{(function (ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}}. Argument types can be interleaved with symbols @code{&optional} and @code{&rest} to match the function's arguments (@pxref{Argument List}). diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 34ea7cf4996..e402eed9437 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -247,6 +247,7 @@ Programming Types * Closure Type:: A function written in Lisp. * Record Type:: Compound objects with programmer-defined types. * Type Descriptors:: Objects holding information about types. +* Type Specifiers:: Expressions which describe types. * Autoload Type:: A type used for automatically loading seldom-used functions. * Finalizer Type:: Runs code when no longer reachable. @@ -1499,6 +1500,99 @@ Type Descriptors An example of a type descriptor is any instance of @code{cl-structure-class}. +@node Type Specifiers +@subsection Type Specifiers + +A type specifier is an expression that denotes a type. A type represents +a set of possible values. Type specifiers can be classified in +primitives and composites. + +@subsubsection Primitive type specifiers. +Primitive types specifiers are the basic types (i.e. not composed by other +type specifiers). + +Built-in primitive types (like @code{integer}, @code{float}, +@code{string} etc) are listed in @xref{Type Hierarchy}. + +@subsubsection Composite type specifiers. +Composite type specifiers allow the definition of complex types by +combining simpler types. + +List of composite composite type specifiers: + +@itemize @bullet +@item @code{or} + +The @code{or} type specifier describes a type that satisfies at least one of +the given types. +@example +(or integer float) +@end example + +@item @code{and} + +Similarly the @code{and} type specifier describes a type that satisfies +at all the given types. + +@item @code{not} + +The @code{not} type specifier defines any type except the specified one. +@example +(not number) +@end example + +@item @code{member} + +The @code{member} type specifier allows to specify a type that includes +only the explicitly listed values. +@example +(member foo bar) +@end example + +@item @code{function} + +The @code{function} type specifier in the form @w{@code{(function +(ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}} used to describe the argument +types and return type of a function. Argument types can be interleaved +with symbols @code{&optional} and @code{&rest} to match the function's +arguments (@pxref{Argument List}). + +The following is to represent a function with: a first parameter of type +@code{symbol}, a second optional parameter of type @code{float} and +returning an @code{integer}: +@example +(function (symbol &optional float) integer) +@end example + +@item @code{integer} + +The @code{integer} type specifier is used to define a subset of integers +by specifying a range. This allows to precisely control which integers +are valid for a given type. + +The general form is: +@example +(integer lower-bound upper-bound) +@end example +Where @code{lower-bound} is the minimum integer value in the range and +@code{upper-bound} the maximum. It is possible to use @code{*} to +indicate no lower or uper limit. + +The following represents all integers from -10 to 10. +@example +(integer -10 10) +@end example + +The following represents 10. +@example +(integer 10 10) +@end example + +The following represents all integers from negative infinity to 10. +@example +(integer * 10) +@end example + @node Autoload Type @subsection Autoload Type --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Thu Nov 14 02:34:08 2024 Received: (at 73626) by debbugs.gnu.org; 14 Nov 2024 07:34:08 +0000 Received: from localhost ([127.0.0.1]:44764 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tBUMh-0006iM-Qm for submit@debbugs.gnu.org; Thu, 14 Nov 2024 02:34:08 -0500 Received: from eggs.gnu.org ([209.51.188.92]:59940) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tBUMf-0006hs-8f for 73626@debbugs.gnu.org; Thu, 14 Nov 2024 02:34:06 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tBUMZ-00014G-RK for 73626@debbugs.gnu.org; Thu, 14 Nov 2024 02:33:59 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=ppHW/uMtEOn5SBXVWa+0xzDYyoCGjnsTzaYMATT2xO4=; b=jaWyCoBq0582 rg094REqTXjjlHg3w6cjV9qRl0clmZD09DZ/JfM9d+RAeLdg+q6I3lOpGRxDv1E11l56/oR+wHQr4 aUhvLWubNGc3O4tHBXslv4M/RO9hWToCAdB3j8mAOl6YMGbvfpGJLmgOyk06JzrhbtA3SpRNVyBbY /6dnDT5cmp1mgH1WTNgW4gC3MdhR2YNG2u2VSto2f6sAiYY8oTaNY4SaCYqMMAEtgsD0Ji7iW5Pok uFc0KL0wxEI08ENfi50J6gOu5iqKJU+PNZz6oUoSsqDJzWjZsAQux04000TpgSVXl2leGekCSzr0z gkMw47yT9EVNr8B79cE6ow==; Date: Thu, 14 Nov 2024 09:33:27 +0200 Message-Id: <86ed3el16g.fsf@gnu.org> From: Eli Zaretskii To: Andrea Corallo In-Reply-To: (message from Andrea Corallo on Wed, 13 Nov 2024 19:27:52 -0500) Subject: Re: bug#73626: 30.0.91; Type specifiers of functions References: <86msjkxdf5.fsf@gnu.org> <86ikthcxjx.fsf@gnu.org> <86seskbi2q.fsf@gnu.org> <86zfm8n51g.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 73626 Cc: 73626@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Andrea Corallo > Cc: 73626@debbugs.gnu.org > Date: Wed, 13 Nov 2024 19:27:52 -0500 > > Okay this is what I'm working on. I felt the need to add a more general > '(elisp)Type Specifiers' node as this was never documented and I think > deserves its own space. > > I referenced it from '(emacs)Name Help' where I mentioned we report > function type specifiers. Also I could reference it from '(elisp) > Declare Form' so that the concept of type specifier (there already > mentioned) is explained. > > There are some mentions of type specifiers in cl.texi which I guess I'll > add some xref as well. > > WDYT? Thanks, some minor comments below. > diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi > index f15b4c5e89d..0f85ff0c832 100644 > --- a/doc/emacs/help.texi > +++ b/doc/emacs/help.texi > @@ -322,6 +322,13 @@ Name Help > yet further information is often reachable by clicking or typing > @key{RET} on emphasized parts of the text. > > +The function type, if known, is expressed with a function type specifier > +(@pxref{Type Specifiers,,,elisp, The Emacs Lisp Reference Manual}), it It would be good to have "function type specifier" in @dfn here, and also have a @cindex entry for that. > -@var{type} is a type specifier in the form @w{@code{(function > +@var{type} is a @ref{Type Specifier} in the form @w{@code{(function "Type Specifiers", in plural. More importantly, using @ref in such a way is not a good idea in Texinfo, it looks good only in the HTML format. For other formats, it is better to use the wordier @var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in the form... > +@node Type Specifiers > +@subsection Type Specifiers Please add an index entry here @cindex type specifier > +A type specifier is an expression that denotes a type. A type represents ^^ Two spaces between sentences. > +a set of possible values. Type specifiers can be classified in > +primitives and composites. Since type specifiers are mostly (only?) used for functions, perhaps the section should explicitly talk about "function type specifiers", or at least mention "function" in several places in the text? > +@subsubsection Primitive type specifiers. > +Primitive types specifiers are the basic types (i.e. not composed by other "i.e." needs a @: after it, since the period doesn't end a sentence. > +Built-in primitive types (like @code{integer}, @code{float}, > +@code{string} etc) are listed in @xref{Type Hierarchy}. @ref, not @xref. The latter is only pertinent at the beginning of a sentence, since it produces a capitalized "See". > +@subsubsection Composite type specifiers. > +Composite type specifiers allow the definition of complex types by > +combining simpler types. Instead of having @subsections here, I'd use a @table (with the composite type specifiers being a nested @table inside that). A @table is easier to read and grasp, and also can save you typing, since you can say @table @code and avoid the need to use @code for each symbol. > +@item @code{and} > + > +Similarly the @code{and} type specifier describes a type that satisfies > +at all the given types. ^^ That "at" should be removed. > +The @code{function} type specifier in the form @w{@code{(function > +(ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}} used to describe the argument The symbols you have in UPPER-CASE should be actually in @var and in lower-case, as we always do with meta-syntactic arguments (i.e., with symbols that stand for something other than themselves literally). > +types and return type of a function. Argument types can be interleaved ^^ Two spaces. > +The @code{integer} type specifier is used to define a subset of integers > +by specifying a range. This allows to precisely control which integers ^^ Likewise. > +are valid for a given type. > + > +The general form is: > +@example > +(integer lower-bound upper-bound) > +@end example > +Where @code{lower-bound} is the minimum integer value in the range and > +@code{upper-bound} the maximum. It is possible to use @code{*} to > +indicate no lower or uper limit. > + > +The following represents all integers from -10 to 10. > +@example > +(integer -10 10) > +@end example > + > +The following represents 10. > +@example > +(integer 10 10) > +@end example > + > +The following represents all integers from negative infinity to 10. > +@example > +(integer * 10) > +@end example I wonder whether the description of the 'integer' type should be in the "primitive types" part, since 'integer' is a primitive type, and mentioned there? A general note: I miss some higher-level background information here, which would explain how these types are generated and how and for what purposes they are used. Such background doesn't have to be too detailed or too technical, but it is important to provide the rationale for this feature. In addition, if there's a value or an advantage to have type information about functions, this section should explain the advantages and encourage Lisp programmers to use the relevant facilities (AFAIU, the 'declare' form; is there anything else?) to provide that information. From debbugs-submit-bounces@debbugs.gnu.org Fri Nov 15 23:22:12 2024 Received: (at 73626) by debbugs.gnu.org; 16 Nov 2024 04:22:12 +0000 Received: from localhost ([127.0.0.1]:51683 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tCAK3-0002hj-SZ for submit@debbugs.gnu.org; Fri, 15 Nov 2024 23:22:12 -0500 Received: from eggs.gnu.org ([209.51.188.92]:50190) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tCAK1-0002hT-Fo for 73626@debbugs.gnu.org; Fri, 15 Nov 2024 23:22:10 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tCAJw-0000dP-4S for 73626@debbugs.gnu.org; Fri, 15 Nov 2024 23:22:04 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=Date:References:Subject:In-Reply-To:To:From: mime-version; bh=+UAOKiKVl4kCdkY28C+EXEufNDSGBJY4og2r7laUeXY=; b=rZ63EoQcQgv6 lhWQIyWTQAPHazxkP8+UIHqzRxQCCQmipDyDgrucKk6ZVY38SjPka70X/HmCIjaZtbIzxssWaSdvz nMhp4PXQFBHhnIS/aYlyqh2Jd/5jWsM/wDhZWdNY7Y4IwKFtxQiCcRWv7mhDzhe+Yl3CgUvBocdLI gSoz4qZPzPq+IzaG8nP1yFOYZ8BWUK9VDKVsv4neJydLIxThlt67jULfFAjRxvdkY3n04Kw1pQw1B v5b33CjCimWlzEpq0YFo00Y9xTJ45kHiY2MJd60oFCW3YmbOplpKj3Hu+xi0tGgebaqublxsTPDoB 183B5OsLyjEIQrpBhRahwg==; Received: from rms by fencepost.gnu.org with local (Exim 4.90_1) (envelope-from ) id 1tCAJr-0006Lo-FB; Fri, 15 Nov 2024 23:22:00 -0500 Content-Type: text/plain; charset=Utf-8 From: Richard Stallman To: Andrea Corallo In-Reply-To: (message from Andrea Corallo on Wed, 13 Nov 2024 19:27:52 -0500) Subject: Re: bug#73626: 30.0.91; Type specifiers of functions References: <86msjkxdf5.fsf@gnu.org> <86ikthcxjx.fsf@gnu.org> <86seskbi2q.fsf@gnu.org> <86zfm8n51g.fsf@gnu.org> Message-Id: Date: Fri, 15 Nov 2024 23:21:59 -0500 X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 73626 Cc: eliz@gnu.org, 73626@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: rms@gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) [[[ To any NSA and FBI agents reading my email: please consider ]]] [[[ whether defending the US Constitution against all enemies, ]]] [[[ foreign or domestic, requires you to follow Snowden's example. ]]] > -@var{type} is a type specifier in the form @w{@code{(function > +@var{type} is a @ref{Type Specifier} in the form @w{@code{(function > (ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}}. Please don't use a cross-reference to stand in for a nominal. It isn't grammatically coherent, and I think it will look completely wrong in some output formats. The right thing to use here is this: type specifier (@pxrer{Type Specifier}) -- Dr Richard Stallman (https://stallman.org) Chief GNUisance of the GNU Project (https://gnu.org) Founder, Free Software Foundation (https://fsf.org) Internet Hall-of-Famer (https://internethalloffame.org) From debbugs-submit-bounces@debbugs.gnu.org Tue Nov 19 04:55:45 2024 Received: (at 73626) by debbugs.gnu.org; 19 Nov 2024 09:55:45 +0000 Received: from localhost ([127.0.0.1]:41121 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tDKxU-0004ua-M0 for submit@debbugs.gnu.org; Tue, 19 Nov 2024 04:55:45 -0500 Received: from eggs.gnu.org ([209.51.188.92]:59416) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tDKxR-0004uM-KL for 73626@debbugs.gnu.org; Tue, 19 Nov 2024 04:55:42 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tDKxE-0005uH-Bs for 73626@debbugs.gnu.org; Tue, 19 Nov 2024 04:55:36 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=wAruVaVQoM7Rh/KEEBg06g7HY+iutJOu7q9OsWcchO8=; b=cc40Kc7TnsaZ+vhEpwiz lcEtJlBoutTuElhDBoBJMiGkxkCxY2RMBL48qe605lfBpmDyEhFGebfy6M4GBXr01/MPZgy43YqST RZuzJxT3E4msOfZQU7l6LFz+Yu0Ieaa4GeH8+5zxD5Oq0OoSLWr//hQNadl4BmA3JgPEozu07Z1rU u+0ExCsfGPoXIIRhkiFr5ArHIvlnM0GAakM49waQk5v5DDBXpC680FLGKj1tbvH5JlLByMoxcWOvv L58rDgDD8Yem4eE1qbUOdt49Lc0CAfW1r2OmHzf1u4nJ6+TnW4/kHUN+eavrfDA9yoWqBQPGU4u0B r7obuDvMMuhVMQ==; Received: from acorallo by fencepost.gnu.org with local (Exim 4.90_1) (envelope-from ) id 1tDKxC-0007ja-13; Tue, 19 Nov 2024 04:55:26 -0500 From: Andrea Corallo To: Eli Zaretskii Subject: Re: bug#73626: 30.0.91; Type specifiers of functions In-Reply-To: <86ed3el16g.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 14 Nov 2024 09:33:27 +0200") References: <86msjkxdf5.fsf@gnu.org> <86ikthcxjx.fsf@gnu.org> <86seskbi2q.fsf@gnu.org> <86zfm8n51g.fsf@gnu.org> <86ed3el16g.fsf@gnu.org> Date: Tue, 19 Nov 2024 04:55:25 -0500 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 73626 Cc: 73626@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) --=-=-= Content-Type: text/plain Eli Zaretskii writes: >> From: Andrea Corallo >> Cc: 73626@debbugs.gnu.org >> Date: Wed, 13 Nov 2024 19:27:52 -0500 >> >> Okay this is what I'm working on. I felt the need to add a more general >> '(elisp)Type Specifiers' node as this was never documented and I think >> deserves its own space. >> >> I referenced it from '(emacs)Name Help' where I mentioned we report >> function type specifiers. Also I could reference it from '(elisp) >> Declare Form' so that the concept of type specifier (there already >> mentioned) is explained. >> >> There are some mentions of type specifiers in cl.texi which I guess I'll >> add some xref as well. >> >> WDYT? > > Thanks, some minor comments below. > >> diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi >> index f15b4c5e89d..0f85ff0c832 100644 >> --- a/doc/emacs/help.texi >> +++ b/doc/emacs/help.texi >> @@ -322,6 +322,13 @@ Name Help >> yet further information is often reachable by clicking or typing >> @key{RET} on emphasized parts of the text. >> >> +The function type, if known, is expressed with a function type specifier >> +(@pxref{Type Specifiers,,,elisp, The Emacs Lisp Reference Manual}), it > > It would be good to have "function type specifier" in @dfn here, and > also have a @cindex entry for that. > >> -@var{type} is a type specifier in the form @w{@code{(function >> +@var{type} is a @ref{Type Specifier} in the form @w{@code{(function > > "Type Specifiers", in plural. More importantly, using @ref in such a > way is not a good idea in Texinfo, it looks good only in the HTML > format. For other formats, it is better to use the wordier > > @var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in > the form... > >> +@node Type Specifiers >> +@subsection Type Specifiers > > Please add an index entry here > > @cindex type specifier >> +A type specifier is an expression that denotes a type. A type represents > ^^ > Two spaces between sentences. > >> +a set of possible values. Type specifiers can be classified in >> +primitives and composites. > > Since type specifiers are mostly (only?) used for functions, perhaps > the section should explicitly talk about "function type specifiers", > or at least mention "function" in several places in the text? They are also usable under `cl-the', 'cl-defstruct' and probably few other cl facilities. (BTW I'd like to have 'cl-the' or a new 'the' wired to the compile machinery for the future). >> +@subsubsection Primitive type specifiers. >> +Primitive types specifiers are the basic types (i.e. not composed by other > > "i.e." needs a @: after it, since the period doesn't end a sentence. > >> +Built-in primitive types (like @code{integer}, @code{float}, >> +@code{string} etc) are listed in @xref{Type Hierarchy}. > > @ref, not @xref. The latter is only pertinent at the beginning of a > sentence, since it produces a capitalized "See". > >> +@subsubsection Composite type specifiers. >> +Composite type specifiers allow the definition of complex types by >> +combining simpler types. > > Instead of having @subsections here, I'd use a @table (with the > composite type specifiers being a nested @table inside that). > > A > @table is easier to read and grasp, and also can save you typing, > since you can say > > @table @code > > and avoid the need to use @code for each symbol. > >> +@item @code{and} >> + >> +Similarly the @code{and} type specifier describes a type that satisfies >> +at all the given types. > ^^ > That "at" should be removed. > >> +The @code{function} type specifier in the form @w{@code{(function >> +(ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}} used to describe the argument > > The symbols you have in UPPER-CASE should be actually in @var and in > lower-case, as we always do with meta-syntactic arguments (i.e., with > symbols that stand for something other than themselves literally). > >> +types and return type of a function. Argument types can be interleaved > ^^ > Two spaces. > >> +The @code{integer} type specifier is used to define a subset of integers >> +by specifying a range. This allows to precisely control which integers > ^^ > Likewise. > >> +are valid for a given type. >> + >> +The general form is: >> +@example >> +(integer lower-bound upper-bound) >> +@end example >> +Where @code{lower-bound} is the minimum integer value in the range and >> +@code{upper-bound} the maximum. It is possible to use @code{*} to >> +indicate no lower or uper limit. >> + >> +The following represents all integers from -10 to 10. >> +@example >> +(integer -10 10) >> +@end example >> + >> +The following represents 10. >> +@example >> +(integer 10 10) >> +@end example >> + >> +The following represents all integers from negative infinity to 10. >> +@example >> +(integer * 10) >> +@end example > > I wonder whether the description of the 'integer' type should be in > the "primitive types" part, since 'integer' is a primitive type, and > mentioned there? 'integer' is a primitive type when used alone, but is a compound one if used as (integer min max). I think I've clarified that. > A general note: I miss some higher-level background information here, > which would explain how these types are generated and how and for what > purposes they are used. Such background doesn't have to be too > detailed or too technical, but it is important to provide the > rationale for this feature. Okay I tried to add some brief context. Attached the latest version where I tried to implement the suggestions. Thanks! Andrea --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=ts.patch diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index f15b4c5e89d..079ea76156f 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -322,6 +322,15 @@ Name Help yet further information is often reachable by clicking or typing @key{RET} on emphasized parts of the text. +@cindex function type specifier + +The function type, if known, is expressed with a @dfn{function type +specifier} (@pxref{Type Specifiers,,,elisp, The Emacs Lisp Reference +Manual}), it will be specified if the type was manually declared by the +programmer or inferred by the compiler. Note that function type +inference works only when native compilation is enabled (@pxref{native +compilation,,, elisp, The Emacs Lisp Reference Manual}). + @vindex help-enable-symbol-autoload If you request help for an autoloaded function whose @code{autoload} form (@pxref{Autoload,,, elisp, The Emacs Lisp Reference Manual}) diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index bf80a21ee9f..bb548441cbc 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -2733,10 +2733,10 @@ Declare Form generation and for deriving more precisely the type of other functions without type declaration. -@var{type} is a type specifier in the form @w{@code{(function -(ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}}. Argument types can be -interleaved with symbols @code{&optional} and @code{&rest} to match the -function's arguments (@pxref{Argument List}). +@var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in the +form @w{@code{(function (ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}}. +Argument types can be interleaved with symbols @code{&optional} and +@code{&rest} to match the function's arguments (@pxref{Argument List}). @var{function} if present should be the name of function being defined. diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 34ea7cf4996..d847f438e0f 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -247,6 +247,7 @@ Programming Types * Closure Type:: A function written in Lisp. * Record Type:: Compound objects with programmer-defined types. * Type Descriptors:: Objects holding information about types. +* Type Specifiers:: Expressions which describe types. * Autoload Type:: A type used for automatically loading seldom-used functions. * Finalizer Type:: Runs code when no longer reachable. @@ -1499,6 +1500,92 @@ Type Descriptors An example of a type descriptor is any instance of @code{cl-structure-class}. +@node Type Specifiers +@subsection Type Specifiers +@cindex type specifier + +A type specifier is an expression that denotes a type. A type +represents a set of possible values. Type specifiers can be classified +in primitives and compounds. + +Type specifiers are in use for several purposes including: documenting +function interfaces through declaration (@pxref{Declare Form}), +specifying structure slot values (@pxref{Structures,,, cl, Common Lisp +Extensions for GNU Emacs Lisp}), type-checking through @code{cl-the} +(@pxref{Declarations,,, cl, Common Lisp Extensions for GNU Emacs Lisp}) +and others. + +@table @asis +@item Primitive type specifiers +Primitive types specifiers are the basic types (i.e.@: not composed by other +type specifiers). + +Built-in primitive types (like @code{integer}, @code{float}, +@code{string} etc) are listed in @ref{Type Hierarchy}. + +@item Compound type specifiers +Compound types serve the purpose of defining more complex or precise +type specifications by combining or modifying simpler types. + +List of compound type specifiers: + +@table @code +@item (or @var{type-1} .. @var{type-n}) +The @code{or} type specifier describes a type that satisfies at least +one of the given types. + +@item (and @var{type-1} .. @var{type-n}) +Similarly the @code{and} type specifier describes a type that satisfies +all the given types. + +@item (not @var{type}) +The @code{not} type specifier defines any type except the specified one. + +@item (member @var{value-1} .. @var{value-n}) +The @code{member} type specifier allows to specify a type that includes +only the explicitly listed values. + +@item (function (@var{arg-1-type} ... @var{arg-n-type}) @var{return-type}) +The @code{function} type specifier is used to describe the argument +types and return type of a function. Argument types can be interleaved +with symbols @code{&optional} and @code{&rest} to match the function's +arguments (@pxref{Argument List}). + +The following is to represent a function with: a first parameter of type +@code{symbol}, a second optional parameter of type @code{float} and +returning an @code{integer}: +@example +(function (symbol &optional float) integer) +@end example + +@item (integer @var{lower-bound} @var{upper-bound}) + +@code{integer} can be used as well as a compound type specifier to +define a subset of integers by specifying a range. This allows to +precisely control which integers are valid for a given type. + +@var{lower-bound} is the minimum integer value in the range and +@var{upper-bound} the maximum. It is possible to use @code{*} to +indicate no lower or uper limit. + +The following represents all integers from -10 to 10. +@example +(integer -10 10) +@end example + +The following represents 10. +@example +(integer 10 10) +@end example + +The following represents all integers from negative infinity to 10. +@example +(integer * 10) +@end example + +@end table +@end table + @node Autoload Type @subsection Autoload Type --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Thu Nov 21 05:52:24 2024 Received: (at 73626) by debbugs.gnu.org; 21 Nov 2024 10:52:24 +0000 Received: from localhost ([127.0.0.1]:49246 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tE4nQ-0003ov-El for submit@debbugs.gnu.org; Thu, 21 Nov 2024 05:52:24 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52190) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tE4nO-0003og-JX for 73626@debbugs.gnu.org; Thu, 21 Nov 2024 05:52:22 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tE4nJ-0007CL-DE for 73626@debbugs.gnu.org; Thu, 21 Nov 2024 05:52:17 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=vEtIZwZ9+7hhmh5GLDGoCvFGgC16AjgOxD+jRdA/QzM=; b=X1SDe/TL6mGF v1CvKu2rXPEcKVuFH8BQOYE3Eef4bmod5O7wPQc6om2ozBt/vbu0m4woc8MDa76K9QpeV95TZo1Gz hh8zaEfoc5WUE/hDQo2j7XgCq6szZI4QVIls98VzoMZ0yX4Nt2FkOYNrVvtw0Ei9J9OMQngusWeAs aTs+BFxA72oGhxwgvn213I12qNxOXz1CGfXjhwjEe5cXtfK3uUm8fBjFumo4HHc3J8NXKAu2VNH5F DY4JPKznG0a1pde/6ay+9J3NVhZmYQAtSbP6x2qk5Kq/T3WH1PoHqkeDemXQobKhfz8bPFPwbPz+K gNyhbWyh3wDa1wdUeqp9Uw==; Date: Thu, 21 Nov 2024 12:52:15 +0200 Message-Id: <86ed34rh9c.fsf@gnu.org> From: Eli Zaretskii To: Andrea Corallo In-Reply-To: (message from Andrea Corallo on Tue, 19 Nov 2024 04:55:25 -0500) Subject: Re: bug#73626: 30.0.91; Type specifiers of functions References: <86msjkxdf5.fsf@gnu.org> <86ikthcxjx.fsf@gnu.org> <86seskbi2q.fsf@gnu.org> <86zfm8n51g.fsf@gnu.org> <86ed3el16g.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 73626 Cc: 73626@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Andrea Corallo > Cc: 73626@debbugs.gnu.org > Date: Tue, 19 Nov 2024 04:55:25 -0500 > > Attached the latest version where I tried to implement the suggestions. > +@var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in the > +form @w{@code{(function (ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}}. ARG-1-TYPE etc. should be in @var and lower-case. Otherwise, this can go in, I think. Thanks. From debbugs-submit-bounces@debbugs.gnu.org Thu Nov 21 08:17:18 2024 Received: (at 73626) by debbugs.gnu.org; 21 Nov 2024 13:17:19 +0000 Received: from localhost ([127.0.0.1]:49530 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tE73e-0001z2-L8 for submit@debbugs.gnu.org; Thu, 21 Nov 2024 08:17:18 -0500 Received: from eggs.gnu.org ([209.51.188.92]:60738) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tE73c-0001yn-9Y for 73626@debbugs.gnu.org; Thu, 21 Nov 2024 08:17:17 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tE71R-0004Pv-Dz for 73626@debbugs.gnu.org; Thu, 21 Nov 2024 08:15:01 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=SwWYilH9kbf8wjOniqDiuY654fNC/SNT5y7fgkV6YgE=; b=G66pr/JcKtEq12P/FVAQ VqbPM7kCdCJ6C/zj6FDynLj6FuV4rW0U0xwF8B3c5bx6Fv0a0bh2Q2Ure/iqVyOy7Afh1C7HJmxX0 +0uN60+z/OKm4oVkz2boz930+IfjeWzkS37oZwDMCiR3/Yi55xUAlLU82qz/hoWIJqnIpxyWWRHYr m6Cptye+9tlpJtci0dbLcUUJoWDJ20ZD9lMSuYzikzz6hCHNVF2PAZcppGZuD6MN8+ghY4UGw25vc pa1uWoPrINXfelouUjkfmoFJwvtmiSLwx1lM4wNTTa1nNOUnZmRZdNJx8wRuRhC8H7fgZfbTosMtd yOMB+PZQgD+laA==; Received: from acorallo by fencepost.gnu.org with local (Exim 4.90_1) (envelope-from ) id 1tE71Q-000241-W1; Thu, 21 Nov 2024 08:15:01 -0500 From: Andrea Corallo To: Eli Zaretskii Subject: Re: bug#73626: 30.0.91; Type specifiers of functions In-Reply-To: <86ed34rh9c.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 21 Nov 2024 12:52:15 +0200") References: <86msjkxdf5.fsf@gnu.org> <86ikthcxjx.fsf@gnu.org> <86seskbi2q.fsf@gnu.org> <86zfm8n51g.fsf@gnu.org> <86ed3el16g.fsf@gnu.org> <86ed34rh9c.fsf@gnu.org> Date: Thu, 21 Nov 2024 08:15:00 -0500 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 73626 Cc: 73626@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Eli Zaretskii writes: >> From: Andrea Corallo >> Cc: 73626@debbugs.gnu.org >> Date: Tue, 19 Nov 2024 04:55:25 -0500 >>=20 >> Attached the latest version where I tried to implement the suggestions. > >> +@var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in the >> +form @w{@code{(function (ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}}. > > ARG-1-TYPE etc. should be in @var and lower-case. =F0=9F=91=8D > Otherwise, this can go in, I think. emacs-30 right? Andrea From debbugs-submit-bounces@debbugs.gnu.org Thu Nov 21 08:49:13 2024 Received: (at 73626) by debbugs.gnu.org; 21 Nov 2024 13:49:13 +0000 Received: from localhost ([127.0.0.1]:49573 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tE7YX-0003Nq-8x for submit@debbugs.gnu.org; Thu, 21 Nov 2024 08:49:13 -0500 Received: from eggs.gnu.org ([209.51.188.92]:50996) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tE7YP-0003ND-3O for 73626@debbugs.gnu.org; Thu, 21 Nov 2024 08:49:10 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tE7YJ-0003HU-LX for 73626@debbugs.gnu.org; Thu, 21 Nov 2024 08:48:59 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=UgGvLcO9qS0iJGw32vj0LL+RwAZCMEtqqJUY6hMXX3A=; b=LBxKUKJiKwwTLS3Mm0XD oLoTgKfUEZfBXCIHqdyHijbrtktG6O3V/bUD5B/cxtV3roKjX6HloW0Rz2KJhXvMaC+vDkYypRqi+ 0Fss3G0bMb5gqIKYFy54I7i/85OEeLxM2WH/pxKcoSCJo7xrAmYs6IWaCaPnew8IPcFSwl3DmpyhQ oc95rMB8MB1s9cfocuAVuSEimaYuypYSCsozgtQd08Pwh4hB/7fIxUsilb6HckrbpHhpPf3X5VdKM 0FY71/h1D791KHmS2w4ZGrTfKwByWJHy3kjng4yz7feNHEhU2dTksgOtFmt3XzHA73QoHPfc7krX1 iLaxR/H1URTAEw==; Date: Thu, 21 Nov 2024 15:48:41 +0200 Message-Id: <86ed34puiu.fsf@gnu.org> From: Eli Zaretskii To: Andrea Corallo In-Reply-To: (message from Andrea Corallo on Thu, 21 Nov 2024 08:15:00 -0500) Subject: Re: bug#73626: 30.0.91; Type specifiers of functions References: <86msjkxdf5.fsf@gnu.org> <86ikthcxjx.fsf@gnu.org> <86seskbi2q.fsf@gnu.org> <86zfm8n51g.fsf@gnu.org> <86ed3el16g.fsf@gnu.org> <86ed34rh9c.fsf@gnu.org> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 73626 Cc: 73626@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Andrea Corallo > Cc: 73626@debbugs.gnu.org > Date: Thu, 21 Nov 2024 08:15:00 -0500 > > Eli Zaretskii writes: > > >> From: Andrea Corallo > >> Cc: 73626@debbugs.gnu.org > >> Date: Tue, 19 Nov 2024 04:55:25 -0500 > >> > >> Attached the latest version where I tried to implement the suggestions. > > > >> +@var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in the > >> +form @w{@code{(function (ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}}. > > > > ARG-1-TYPE etc. should be in @var and lower-case. > > 👍 > > > Otherwise, this can go in, I think. > > emacs-30 right? Yes, please. From debbugs-submit-bounces@debbugs.gnu.org Thu Nov 21 09:57:13 2024 Received: (at 73626-done) by debbugs.gnu.org; 21 Nov 2024 14:57:14 +0000 Received: from localhost ([127.0.0.1]:51307 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tE8cL-00074Q-J3 for submit@debbugs.gnu.org; Thu, 21 Nov 2024 09:57:13 -0500 Received: from eggs.gnu.org ([209.51.188.92]:58984) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tE8cJ-00074H-DS for 73626-done@debbugs.gnu.org; Thu, 21 Nov 2024 09:57:12 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tE8cE-0000N5-3K for 73626-done@debbugs.gnu.org; Thu, 21 Nov 2024 09:57:06 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=A4lK/R8JQceZlkulXl1TAnQjTzenb47cdrIvycU3b4k=; b=E5W9njOmEWIL3NxlLYsw +j3uIHL/IHzSSsh3eV8iIGVwcWRhGmjeJoAK1JYex0VhU1WPX+4PeTsOarvURXv4JKciuj8Z5oPNg UxlRTSkgn3aj7LGf1hgtmzR5HFnmli4jn1lz69t2it+PjxhQr2ExEF26CfGzey5gLm9yDO8HTVH55 8vWwsLpObP8jYl9xqxfulQjBNFO6llQICGG7R6K62Comjlu0+tEToQ0RK5w1169Je/2yiJtfWnwWe 1GXT1tELX8rhKfTes2wXpFoRaZ3OvsZ2Y+jdnTCvi8d1lEnAlJhuWIoAhxBg93MQIRPeaPzaCK9Dn 6g5sIpMmAJLU8w==; Received: from acorallo by fencepost.gnu.org with local (Exim 4.90_1) (envelope-from ) id 1tE8cC-0001g9-Kz; Thu, 21 Nov 2024 09:57:04 -0500 From: Andrea Corallo To: Eli Zaretskii Subject: Re: bug#73626: 30.0.91; Type specifiers of functions In-Reply-To: <86ed34puiu.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 21 Nov 2024 15:48:41 +0200") References: <86msjkxdf5.fsf@gnu.org> <86ikthcxjx.fsf@gnu.org> <86seskbi2q.fsf@gnu.org> <86zfm8n51g.fsf@gnu.org> <86ed3el16g.fsf@gnu.org> <86ed34rh9c.fsf@gnu.org> <86ed34puiu.fsf@gnu.org> Date: Thu, 21 Nov 2024 09:57:04 -0500 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 73626-done Cc: 73626-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Eli Zaretskii writes: >> From: Andrea Corallo >> Cc: 73626@debbugs.gnu.org >> Date: Thu, 21 Nov 2024 08:15:00 -0500 >>=20 >> Eli Zaretskii writes: >>=20 >> >> From: Andrea Corallo >> >> Cc: 73626@debbugs.gnu.org >> >> Date: Tue, 19 Nov 2024 04:55:25 -0500 >> >>=20 >> >> Attached the latest version where I tried to implement the suggestion= s. >> > >> >> +@var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in the >> >> +form @w{@code{(function (ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}}. >> > >> > ARG-1-TYPE etc. should be in @var and lower-case. >>=20 >> =F0=9F=91=8D >>=20 >> > Otherwise, this can go in, I think. >>=20 >> emacs-30 right? > > Yes, please. That's done thanks, closing Andrea From unknown Tue Aug 19 21:04:04 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Fri, 20 Dec 2024 12:24:07 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator