From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: Opaque objects and Emacs documentation Date: Fri, 17 Jul 2020 08:41:34 -0700 (PDT) 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; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="6462"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Eli Zaretskii , Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Jul 17 17:42:18 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 1jwSV7-0001WE-TC for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 17:42:18 +0200 Original-Received: from localhost ([::1]:44772 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwSV6-0002BG-TK for ged-emacs-devel@m.gmane-mx.org; Fri, 17 Jul 2020 11:42:16 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:43476) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwSUZ-0001kc-2W for emacs-devel@gnu.org; Fri, 17 Jul 2020 11:41:43 -0400 Original-Received: from aserp2120.oracle.com ([141.146.126.78]:57864) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwSUW-0001AA-T0; Fri, 17 Jul 2020 11:41:42 -0400 Original-Received: from pps.filterd (aserp2120.oracle.com [127.0.0.1]) by aserp2120.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 06HFX6Yj154698; Fri, 17 Jul 2020 15:41:37 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2020-01-29; bh=lkzSSmvlsJlInBOW19GkUY2U6QNCnAGZuoH9tWfLjK4=; b=ZYoBC6vxcy3W2InIMWpktvJA+1LHv3SvidikQ+mjk/WbIOo5D3NyxuwOU1XXrunQTh+L VlnnOESMTP2wlyHyQ5fkj63LkeiRGzkQicqmGnvYesuDcp+uWrYHlrjHzJ+sYT878u5d cSv4OPA4OL57iPDg5VHWTzm/VmYJtLNuilGIcdjQNF5/lBdzlCXoYkooAh/byYEDwaKX AP4zU2Dlfr19OB378sxiLljJ76Ch83X2cARmoTQ+TzwrzIOxfOtQfKp+NZG+H51R1Yjy lNiaTJ8zQAg3NSxrBvMYeenql19PkJvYhcRmIcUiSREJMbDBOX7K9K2qbFn2NilCn3BX uw== Original-Received: from aserp3020.oracle.com (aserp3020.oracle.com [141.146.126.70]) by aserp2120.oracle.com with ESMTP id 3275cmqyae-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Fri, 17 Jul 2020 15:41:37 +0000 Original-Received: from pps.filterd (aserp3020.oracle.com [127.0.0.1]) by aserp3020.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 06HFXkvY078466; Fri, 17 Jul 2020 15:41:36 GMT Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by aserp3020.oracle.com with ESMTP id 32baunx4f7-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 17 Jul 2020 15:41:36 +0000 Original-Received: from abhmp0003.oracle.com (abhmp0003.oracle.com [141.146.116.9]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id 06HFfZvJ012619; Fri, 17 Jul 2020 15:41:35 GMT In-Reply-To: <<83a6zyk4tt.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.5017.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9685 signatures=668680 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=48 mlxscore=0 mlxlogscore=999 malwarescore=0 spamscore=0 adultscore=0 phishscore=0 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2006250000 definitions=main-2007170114 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9685 signatures=668680 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=48 priorityscore=1501 bulkscore=0 adultscore=0 lowpriorityscore=0 phishscore=0 spamscore=0 impostorscore=0 malwarescore=0 mlxlogscore=999 clxscore=1015 mlxscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2006250000 definitions=main-2007170114 Received-SPF: pass client-ip=141.146.126.78; envelope-from=drew.adams@oracle.com; helo=aserp2120.oracle.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/07/17 11:41:37 X-ACL-Warn: Detected OS = Linux 3.1-3.10 [fuzzy] X-Spam_score_int: -63 X-Spam_score: -6.4 X-Spam_bar: ------ X-Spam_report: (-6.4 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H2=-1, SPF_HELO_PASS=-0.001, SPF_PASS=-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:253033 Archived-At: FWIW, since the question was asked - I'm in favor of documenting pretty much all Emacs-Lisp functions and variables _all the way down_. (Even lambda expressions sometimes deserve a doc string. And yes, a comment can also serve, but a doc string is generally better for describing what something is or does. A comment is generally good for describing design decisions or unobvious code considerations.) And this is so whether or not someone considers this or that particular thing to be "internal", whether just for now or for all time. If you write code for yourself, any designation of "internal" is just a note to yourself that either (a) the code in question is asking to be revisited and possibly changed later, perhaps including its interfaces with other code, or (b) the code in question is tricky or fragile, so fiddling with it can be asking for trouble. With free software, all code we write is code for ourselves, because ourselves includes everyone, now or later. This means that all labeling of "internal" is only a comment saying (a) or (b), above. Such labeling is _never_ a reason, with free software, _not_ to describe something. We're not (should not be) trying to hide anything from anyone, including ourselves. There's too much labeling of stuff in Emacs as "internal", IMO, and this has increased over time. For the most part it's not necessary or useful. Too often, I think, such branding as "internal" is really a cop-out from someone who isn't interested in the doc/help, or doesn't want to take the time to describe things (e.g. in English), or has trouble doing so, or just has a mental "block" about doing so (similar to math phobia), or even is unsure of the thing to be described and wants to save the possible embarrassment of offering an off-the-mark description. Such "feeling" motivations do happen sometimes. Such feelings can be understandable, but they are never a reason why the things in question _shouldn't_ be described. They can be reasons why the person having such feelings shouldn't need to be the one to document those things. They're just not a reason why things shouldn't be documented at all. The case of generated functions and variables is a special one. Generic functions are one example of creating things programmatically. `cl-defstruct' is another example. Even things like `define-minor-mode' are examples. In these cases we need to (should, IMO) find ways to: 1. Programmatically add _some_ useful doc, when feasible. We've done that for things like `define-minor-mode', but there's still room for improvement. 2. Provide ways for the programmatically added doc to be manually tweaked (supplemented, replaced). 3. Actually _do_ such manual tweaking. And to the extent that we haven't provided good solutions for #1 and #2, just provide the doc manually, whenever possible. Lisp is not your average language. And free software doesn't have the same constraints and purposes as proprietary software. _Some_ of the typical encapsulation and rendering of things as opaque/internal is motivated by a spirit of protection of property/control that doesn't apply to free software. The point is not to not have abstractions or use macros or higher-order functions. It's not to _force_ someone to dive deep for understanding. The point is to provide help all the way up and down. There's no good reason _not_ to do that, IMO. "Don't look! - INTERNAL" is, in particular, not a good reason. It's not a reason at all, except perhaps in the context of protecting private property, which we're not in the business of doing, here. Opaqueness should be anathema to free software. Just one opinion. And thanks for posing the question, Eli.