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: Opaque objects and Emacs documentation Date: Fri, 17 Jul 2020 12:48:08 -0400 Message-ID: References: <20200712184908.13140.5739@vcs0.savannah.gnu.org> <20200712184909.BBC61209B1@vcs0.savannah.gnu.org> <7bf4d6ef-c0ec-43dc-ad5d-f6e81422ad90@yandex.ru> <83zh84m5ws.fsf@gnu.org> <3dd1c224-69b2-40af-5b2e-43a310253632@yandex.ru> <83tuybmtxs.fsf@gnu.org> <859f594b-1343-6d26-e1ac-7157c44eb56c@yandex.ru> <83a6zyk4tt.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="30102"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) Cc: emacs-devel@gnu.org, Dmitry Gutov To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Jul 17 18:49:02 2020 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 1jwTXi-0007iA-D6 for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 18:49:02 +0200 Original-Received: from localhost ([::1]:51792 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwTXh-00010Z-DX for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 12:49:01 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:41186) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwTWy-000894-Ec for emacs-devel@gnu.org; Fri, 17 Jul 2020 12:48:16 -0400 Original-Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:54820) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwTWv-0007EF-RR; Fri, 17 Jul 2020 12:48:15 -0400 Original-Received: from pmg2.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id 0041581377; Fri, 17 Jul 2020 12:48:12 -0400 (EDT) Original-Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id 4FC3180B63; Fri, 17 Jul 2020 12:48:10 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1595004490; bh=4c33feI5HASWxjcyFcV6DXXciHZvWcJpLEfg8IsTTa8=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=R5o2A4ImyXe3ZZwY4M4f1FSo+sNWy7F8+0FjxVAx+AexQJTtvEMk7EjPU9mvOnKGu itR4RWg8XoczaFMne+msp1/Axjk+4G1eC26OSMrxw9ymhN5nKaZ81sm3/kvrix13aT HNwWo0up0Fo+ahpQtoveUYw6c8J02ZGeELu7aHR1j0E+jTBJZeIk6Ne0ZFOVb8Wv4D 9Ctpw0vX4dkLXM3w6qA8k0XoXXuPafgVTSK8fxt01sshvXwOKiSAG+IsIqPPhEGmqv s0nKhFE9XFVtlNJpOl7ASvtbRZ5IIkZ5ZHp/EDOknpAlRHpCUbwYN/H7BilLhPvwGo 7zQIBhiwI+HGA== Original-Received: from milanesa (76-10-180-175.dsl.teksavvy.com [76.10.180.175]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id BD46B12074C; Fri, 17 Jul 2020 12:48:09 -0400 (EDT) In-Reply-To: <83a6zyk4tt.fsf@gnu.org> (Eli Zaretskii's message of "Fri, 17 Jul 2020 09:56:14 +0300") Received-SPF: pass client-ip=132.204.25.50; envelope-from=monnier@iro.umontreal.ca; helo=mailscanner.iro.umontreal.ca X-detected-operating-system: by eggs.gnu.org: First seen = 2020/07/17 12:20:17 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] 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, URIBL_BLOCKED=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 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:253038 Archived-At: > Basically, you are saying that in your opinion this is as it should > be, and cannot be helped. > > Which I think is against long-time Emacs tradition for documenting its > interfaces, and by that facilitating extensibility. It is IMO wrong > to fill Emacs application levels with opaque objects which cannot be > usefully described; they should be a rare exception, but definitely > not the rule. I believe in this specific case, the issue is that the shape can and will change and not only over time. The only thing defined is an interface and any code which relies on more than this interface (e.g. a function which relies on completion-tables being lists of strings) will break sooner or later. Of course, that doesn't prevent the doc from giving *examples* to show the intended behavior. Stefan