From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: master 48ac40e60e: ; Fix last change. Date: Sun, 14 Aug 2022 22:37:10 -0400 Message-ID: References: <166049949398.16955.13217655219158269477@vcs2.savannah.gnu.org> <20220814175134.47827C09BFD@vcs2.savannah.gnu.org> <8335dyk779.fsf@gnu.org> <83zgg6irx9.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="27919"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Aug 15 04:37:58 2022 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 1oNPzK-00073U-9a for ged-emacs-devel@m.gmane-mx.org; Mon, 15 Aug 2022 04:37:58 +0200 Original-Received: from localhost ([::1]:52060 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oNPzJ-00016s-9v for ged-emacs-devel@m.gmane-mx.org; Sun, 14 Aug 2022 22:37:57 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:45934) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oNPye-0000Bk-Jp for emacs-devel@gnu.org; Sun, 14 Aug 2022 22:37:16 -0400 Original-Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:51166) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oNPyc-0001Ec-EK; Sun, 14 Aug 2022 22:37:15 -0400 Original-Received: from pmg1.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id 4A43E100134; Sun, 14 Aug 2022 22:37:13 -0400 (EDT) Original-Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id E43F110008C; Sun, 14 Aug 2022 22:37:11 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1660531031; bh=gqaoNWrGyFgqcmD+mPMleT0sznRmH6xNXm24nGWmXCw=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=WqXOzUXqKBxnKcfWReSPa18s7GbEEvJ7csrAC8KraiijV463EFmj1y+Kx7wyFi/Ug ZqcYUVQhFC5k86BzZWVru+B1t2TA5UNLmrzl7IKM2wwuJJpioTM6oqZocA7TyikSk4 PKeglmUlF6di47TZf92fnYx1hYtLUG2Rvf9J3AAvu8+M3VP8mpW+mrveNMxomplHMT Hr8b6uYruZsHh5PXu7uw2futEvKPYDldXXVbiZLmQyx/UOPFtKguGD01lBGP3m15qQ eRDl02gDuYbXY9JIOLt3USK+4SIgXoLtknO/a2GFYEojAu8Xn0HCxZpGzPNQNGO2qo OUEc6wzM7HlAg== Original-Received: from pastel (unknown [45.72.195.111]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id C4F771201F4; Sun, 14 Aug 2022 22:37:11 -0400 (EDT) In-Reply-To: <83zgg6irx9.fsf@gnu.org> (Eli Zaretskii's message of "Sun, 14 Aug 2022 21:46:58 +0300") Received-SPF: pass client-ip=132.204.25.50; envelope-from=monnier@iro.umontreal.ca; helo=mailscanner.iro.umontreal.ca X-Spam_score_int: -42 X-Spam_score: -4.3 X-Spam_bar: ---- X-Spam_report: (-4.3 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_MED=-2.3, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:293469 Archived-At: >> It's not a very specific API. It's a kind of "abstract super class", so >> in my book it should be defined not by enumerating its current >> subclasses but by giving a meaningful way to decide whether a given >> class should be a subclass or not. > Sorry, I reject the idea that abstract classes cannot be usefully > documented in concrete terms. At least there's no excuse for not > trying. I'm not opposed to doing it, but I feel that it's not sufficient because it doesn't say why that abstract class exists (i.e. what it is that makes it meaningful to group those different classes under that abstract class). To me it's akin to describing a particular image by listing the pixels it contains and their color but without saying what the image represents. We may be able to use our brain to figure out what the image represents, but it's not always obvious that everyone will end up with the same understanding. How 'bout the patch below? Stefan diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index ddf7cff6c2e..983dfe2ec59 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -219,10 +219,12 @@ What Is a Function @defun compiled-function-p object This function returns @code{t} if @var{object} is a function object -that was either built-in (a.k.a.@: ``primitive'', @pxref{What Is a -Function}), or byte-compiled (@pxref{Byte Compilation}), or -natively-compiled (@pxref{Native Compilation}), or a function loaded -from a dynamic module (@pxref{Dynamic Modules}). +that is not in the form of ELisp source code but something like +machine code or byte code instead. More specifically it returns +@code{t} if the function is built-in (a.k.a.@: ``primitive'', +@pxref{What Is a Function}), or byte-compiled (@pxref{Byte +Compilation}), or natively-compiled (@pxref{Native Compilation}), or +a function loaded from a dynamic module (@pxref{Dynamic Modules}). @end defun @defun subr-arity subr