From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: Making DOC argument of define-minor-mode optional Date: Wed, 23 Nov 2016 08:35:05 -0800 (PST) Message-ID: <41b59c33-1be1-440e-a9b1-efb97c6e14a8@default> References: <83eg226vr5.fsf@gnu.org> <87lgwaxk3z.fsf@petton.fr> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1479918934 5222 195.159.176.226 (23 Nov 2016 16:35:34 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 23 Nov 2016 16:35:34 +0000 (UTC) Cc: emacs-devel@gnu.org To: Nicolas Petton , Eli Zaretskii , Philipp Stephani Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Nov 23 17:35:29 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1c9aW6-0008RW-BJ for ged-emacs-devel@m.gmane.org; Wed, 23 Nov 2016 17:35:26 +0100 Original-Received: from localhost ([::1]:34843 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c9aW8-0004zP-4x for ged-emacs-devel@m.gmane.org; Wed, 23 Nov 2016 11:35:28 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:50705) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c9aVw-0004yh-0L for emacs-devel@gnu.org; Wed, 23 Nov 2016 11:35:16 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c9aVv-00013I-5v for emacs-devel@gnu.org; Wed, 23 Nov 2016 11:35:16 -0500 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:24726) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1c9aVr-000106-BN; Wed, 23 Nov 2016 11:35:11 -0500 Original-Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id uANGZ7Xs028358 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 23 Nov 2016 16:35:07 GMT Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id uANGZ7kT029729 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 23 Nov 2016 16:35:07 GMT Original-Received: from abhmp0012.oracle.com (abhmp0012.oracle.com [141.146.116.18]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id uANGZ68w004022; Wed, 23 Nov 2016 16:35:06 GMT In-Reply-To: <87lgwaxk3z.fsf@petton.fr> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 12.0.6753.5000 (x86)] X-Source-IP: aserv0022.oracle.com [141.146.126.234] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] [fuzzy] X-Received-From: 141.146.126.69 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:209569 Archived-At: > >> the docstring created by define-minor-mode with nil DOC is useful > >> and often better than what users write. > >> Should DOC therefore be optional? > > > > Not sure we would like to educate Lisp programmers to stop > > thinking about good doc strings. >=20 > I agree. Me too. And definers of user-facing things, such as defcustom and defface, do require DOC. Other definers, such as defconst and defvar, do not require it. On the other hand, OP raises a real issue, I think. I'd be in favor of (somehow) automatically having the definer-provided DOC be augmented by a link that shows the generic `define-minor-mode' doc, or similar. IOW: 1. Definers should need to provide a DOC string (even if they can fake it with "", which is not encouraged). 2. Users of the mode should have access to the generic information also. It should be sufficient that the DOC in the definition provides mode-specific information. It should not need to tell users general things about using a minor mode.