From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#73626: 30.0.91; Type specifiers of functions Date: Thu, 14 Nov 2024 09:33:27 +0200 Message-ID: <86ed3el16g.fsf@gnu.org> References: <86msjkxdf5.fsf@gnu.org> <86ikthcxjx.fsf@gnu.org> <86seskbi2q.fsf@gnu.org> <86zfm8n51g.fsf@gnu.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="3735"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 73626@debbugs.gnu.org To: Andrea Corallo Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Nov 14 08:35:27 2024 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1tBUNy-0000od-LQ for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 14 Nov 2024 08:35:26 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tBUNc-0000SG-2J; Thu, 14 Nov 2024 02:35:04 -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 1tBUNa-0000RD-M9 for bug-gnu-emacs@gnu.org; Thu, 14 Nov 2024 02:35:02 -0500 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tBUNa-0001H6-AB for bug-gnu-emacs@gnu.org; Thu, 14 Nov 2024 02:35:02 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=References:In-Reply-To:From:Date:To:Subject; bh=ppHW/uMtEOn5SBXVWa+0xzDYyoCGjnsTzaYMATT2xO4=; b=DB5xqLA3kv8T1lLK0s26KFVlOxNEdmOZkiX7NBCFWzp/MWeNpG3uhB2chBdu99RlvKBXGv+tNfBWvQw4HD1AzdKIFgElkEg7vHo3Kk0KQA3pSI0tkcTjANvoxnHDhQO2vx8UTkku4+2shLT/zwi9rnu+wAX7h0szJsYdMXeVFcF+zJfOgCKwOlGEmJBnZlZsFZfJ1wWhLng05EzY/NXTCwNvAjNMujGoU5b/pJnrOfqCr6z7WWeeEn8krUg57C3zqv8gjikqD+kEkOuSze94cxn6V7dz0QB+fx/Ce2d4hCk18nZIhrO+8yD0qhr1Dip0uza6ZE9mSnk6lMhLPUxMxQ==; Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1tBUNa-0006jw-3V for bug-gnu-emacs@gnu.org; Thu, 14 Nov 2024 02:35:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 14 Nov 2024 07:35:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 73626 X-GNU-PR-Package: emacs Original-Received: via spool by 73626-submit@debbugs.gnu.org id=B73626.173156964825818 (code B ref 73626); Thu, 14 Nov 2024 07:35:02 +0000 Original-Received: (at 73626) by debbugs.gnu.org; 14 Nov 2024 07:34:08 +0000 Original-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 Original-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 Original-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==; In-Reply-To: (message from Andrea Corallo on Wed, 13 Nov 2024 19:27:52 -0500) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:295306 Archived-At: > 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.