From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: tomas@tuxteam.de Newsgroups: gmane.emacs.devel Subject: Re: Opaque objects and Emacs documentation Date: Tue, 21 Jul 2020 12:29:11 +0200 Message-ID: <20200721102911.GB446@tuxteam.de> References: <831rlajock.fsf@gnu.org> <1fcdc463-b3ab-2d32-31d7-904783ae0d81@yandex.ru> <83y2nii6sk.fsf@gnu.org> <69716ecb-8984-23e0-8b44-322ea3582384@yandex.ru> <20200721085735.GA446@tuxteam.de> <6d5c2ee4-ebba-8050-3195-2a3cf38ecb3e@yandex.ru> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="s2ZSL+KKDSLx8OML" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="34312"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mutt/1.5.21 (2010-09-15) Cc: emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue Jul 21 12:29:55 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 1jxpX1-0008qm-Dv for ged-emacs-devel@m.gmane-mx.org; Tue, 21 Jul 2020 12:29:55 +0200 Original-Received: from localhost ([::1]:55748 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jxpX0-00031V-Ey for ged-emacs-devel@m.gmane-mx.org; Tue, 21 Jul 2020 06:29:54 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:57460) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jxpWV-0002cX-KD for emacs-devel@gnu.org; Tue, 21 Jul 2020 06:29:23 -0400 Original-Received: from mail.tuxteam.de ([5.199.139.25]:49987) by eggs.gnu.org with esmtps (TLS1.2:DHE_RSA_AES_128_CBC_SHA1:128) (Exim 4.90_1) (envelope-from ) id 1jxpWT-0003Al-I7 for emacs-devel@gnu.org; Tue, 21 Jul 2020 06:29:23 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=tuxteam.de; s=mail; h=In-Reply-To:Content-Type:MIME-Version:References:Message-ID:Subject:Cc:To:From:Date; bh=J9Fby/QQsxTruXzF0ccKVWQ3M6oMN44Q71Z9ZA3zsOQ=; b=iqYASjiXsbVJ88UsPeHlOgVJJ0r0LmvN3YbBg1Tqgedjd2c9/6E/X38/Xo9iMcSHfmccdvxg7SoLFIZ3HmEL/VPlvKGLjLQIRLrX0i1QCfnRfQ4E3ZvVBQcFkVuO9RsZu+alSF2uZbEG8SeZr15uGbpFlIbJ4jGjS7Sd0fickfcFiaapLHPXoC9sDgJhk0/Nz7HPA4P0Tf+zyC3KjM9GrNvNZM5qdg6U/UDmacNwh3oMK/t+va4XeGN0+kgZvLh+CoM2iH3jm5nRS+iK1IHCHHWeDa6v2eR0wpCSLDd0BTC/CKySJPZrQmt1lO8ewvgEA/inCCLAu0M4ygR971qXbQ==; Original-Received: from tomas by mail.tuxteam.de with local (Exim 4.80) (envelope-from ) id 1jxpWJ-0001IP-R5; Tue, 21 Jul 2020 12:29:11 +0200 Content-Disposition: inline In-Reply-To: <6d5c2ee4-ebba-8050-3195-2a3cf38ecb3e@yandex.ru> Received-SPF: pass client-ip=5.199.139.25; envelope-from=tomas@tuxteam.de; helo=mail.tuxteam.de X-detected-operating-system: by eggs.gnu.org: First seen = 2020/07/21 04:57:36 X-ACL-Warn: Detected OS = Linux 3.1-3.10 [fuzzy] X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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:253133 Archived-At: --s2ZSL+KKDSLx8OML Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Tue, Jul 21, 2020 at 01:14:16PM +0300, Dmitry Gutov wrote: > On 21.07.2020 11:57, tomas@tuxteam.de wrote: >=20 > >I don't think it's intentional, but please reconsider this: >=20 > Reconsider the phrasing? >=20 > >>[...] The core of the dispute is whether > >>project-current's docstring should document the return value in > >>detail (giving an example of built-in project instances's > >>structure). Eli is insisting on it because (AFAICT) that suits his > >>thought process and he thinks that will help users/clients to make > >>sense of how things work. > > > >in a few words: Eli's thought process vs... >=20 > That's how I understand it. And there is nothing bad in documenting > code along the lines of someone's thoughts. It's generally a good > thing. But not when it defeats the purpose of how the code is > written. >=20 > >>I am adamantly against this because it's against the design (clients > >>should program against the public interface, not against the > >>implementation), and is likely to encourage incorrect programs. > > > >... The Right Way To Do It (TM). > > > >It comes across as a little... biased. Which is understandable, > >but not a good position when bargaining, nevertheless ;-) >=20 > The whole situation is biased, in multiple respects. Yes, and I do feel your pain. Don't take this as a personal attack, that'd the last thing I wish for. It's just that I do understand also Eli's position, and I feel that it has merit -- it is unfair to depict it as "just Eli's thoughts". Cheers -- t --s2ZSL+KKDSLx8OML Content-Type: application/pgp-signature; name="signature.asc" Content-Description: Digital signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.12 (GNU/Linux) iEYEARECAAYFAl8Ww3cACgkQBcgs9XrR2kYpagCfcDbDtkign7DPDFiruhy8m9Rt hhQAn0sE9Qk7ylzXyfj0KnHFuGY0tb0b =CJX2 -----END PGP SIGNATURE----- --s2ZSL+KKDSLx8OML--