From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: master e4896fc 1/2: Add a new 'flex' completion style Date: Thu, 14 Feb 2019 15:22:12 +0000 (UTC) Message-ID: References: <20190213212413.868.40960@vcs0.savannah.gnu.org> <20190213212414.D6F4C209C6@vcs0.savannah.gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="92049"; mail-complaints-to="usenet@blaine.gmane.org" Cc: emacs-devel To: =?utf-8?B?Sm/Do28gVMOhdm9yYQ==?= , Robert Pluim Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Feb 14 16:23:28 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1guIrH-000Nmj-Kn for ged-emacs-devel@m.gmane.org; Thu, 14 Feb 2019 16:23:27 +0100 Original-Received: from localhost ([127.0.0.1]:50136 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1guIrF-00076e-K0 for ged-emacs-devel@m.gmane.org; Thu, 14 Feb 2019 10:23:25 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:54464) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1guIqB-00075u-8v for emacs-devel@gnu.org; Thu, 14 Feb 2019 10:22:19 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1guIqA-0000v3-Eg for emacs-devel@gnu.org; Thu, 14 Feb 2019 10:22:19 -0500 Original-Received: from aserp2130.oracle.com ([141.146.126.79]:49238) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1guIqA-0000t7-3Y for emacs-devel@gnu.org; Thu, 14 Feb 2019 10:22:18 -0500 Original-Received: from pps.filterd (aserp2130.oracle.com [127.0.0.1]) by aserp2130.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x1EFKExu027706; Thu, 14 Feb 2019 15:22:14 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-2018-07-02; bh=W3shthze4qSF3CsOjdYizkq8+qysKQKzRFitSIPIOWE=; b=If7EaYwqIEoX/el/D+EpcZa11yfPIVqulNsap5Csojt/rHHEU2tIC4fMjUikzN26NfoO mvuCvIWdxA+ytEI9FnvF0OnosWZDxBpFzcLHDwMJi3as5cI4J6rUc82dmO5nW+FFcr9P 3swj2qD6+gotIEJvQ6AcD5TKq7hlmNYv1T7+HfzHG2YPNMQjje9P1VM0BW3rL0Lh0Nqc SlHHnmcab/7EgGiRLRA2tkDnyZ5elpfXIQZS2L7OslRGy9k3RRSYsVC+sRhMO8maZUu9 pv6JoJo2UM0VTC3IbP4SYeCWy0/WUaqaBITmQVhanCvStokfmI7KCfF9AkU0yJbS4O/t ng== Original-Received: from aserv0021.oracle.com (aserv0021.oracle.com [141.146.126.233]) by aserp2130.oracle.com with ESMTP id 2qhre5rkfa-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 14 Feb 2019 15:22:14 +0000 Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by aserv0021.oracle.com (8.14.4/8.14.4) with ESMTP id x1EFMDO1024258 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 14 Feb 2019 15:22:13 GMT Original-Received: from abhmp0009.oracle.com (abhmp0009.oracle.com [141.146.116.15]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id x1EFMD4E022955; Thu, 14 Feb 2019 15:22:13 GMT In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4810.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=9167 signatures=668683 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1902140107 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [generic] X-Received-From: 141.146.126.79 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 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.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:233326 Archived-At: > what is better: writing a subpar docstring for an > internal function, or keeping it undocumented. That depends on what makes it subpar. A subpar doc string can be so just because it is slightly incomplete or slightly incorrect or misleading. In this case it might well be better than no doc string. But a subpar doc string can also be so because it gives a very wrong idea of what the object is/does. In this case it might be worse than no doc string. This should be obvious. The devil is in the details. In general, we should have doc strings - including for "internal" functions (IMHO). But the doc strings should be accurate and helpful, not inaccurate or harmful. (Not saying anything about the doc strings mentioned in this thread. Just responding to your wish for a too-general rule/judgment as to which is better: bad or none.)