From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Philipp Stephani Newsgroups: gmane.emacs.devel Subject: Re: Making DOC argument of define-minor-mode optional Date: Sun, 27 Nov 2016 21:13:14 +0000 Message-ID: References: <83eg226vr5.fsf@gnu.org> <87lgwaxk3z.fsf@petton.fr> <41b59c33-1be1-440e-a9b1-efb97c6e14a8@default> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=001a11444cc46426a105424ed32e X-Trace: blaine.gmane.org 1480281246 17772 195.159.176.226 (27 Nov 2016 21:14:06 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 27 Nov 2016 21:14:06 +0000 (UTC) Cc: emacs-devel@gnu.org To: Drew Adams , Nicolas Petton , Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Nov 27 22:14:01 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 1cB6lt-0003al-3q for ged-emacs-devel@m.gmane.org; Sun, 27 Nov 2016 22:14:01 +0100 Original-Received: from localhost ([::1]:55635 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cB6lw-0007SL-Om for ged-emacs-devel@m.gmane.org; Sun, 27 Nov 2016 16:14:04 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:43049) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cB6lM-00078P-VE for emacs-devel@gnu.org; Sun, 27 Nov 2016 16:13:29 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cB6lL-0007wi-RN for emacs-devel@gnu.org; Sun, 27 Nov 2016 16:13:28 -0500 Original-Received: from mail-wm0-x22f.google.com ([2a00:1450:400c:c09::22f]:34115) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cB6lK-0007vO-4L; Sun, 27 Nov 2016 16:13:26 -0500 Original-Received: by mail-wm0-x22f.google.com with SMTP id u144so37164726wmu.1; Sun, 27 Nov 2016 13:13:26 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=sUb+EroXyapxIDNsLF15Gn1e5rtisddXEEuzUWCX6ak=; b=BIDKXDz0fV6I4aDA3oR9ZY/GR11scWCUWmraGc+LpMTT+WvfWOMEuI2u5rEtFNkI/2 0IB2bQy5YQEb/BK5nIgGIKZaozCAKx1XJbnicrRziMwE7QQGhpMNvGdRxTqOSxeFSvtF ur/VfHsr8zP/ZV1LzKemrIl9GJ8+iKKeYwJ8+p1WHJnH/yymHIU+J3Qslu93ww/D0lF0 WFOlvw99bvF/ULWi7kAuQXzPKnN8M0XOYxu3Z5HRUCg6+cEMa7DuYyFrq/NkZWEAy1qr W92W9XLh9eD+EgAM/fknMwT7zFdidsa7i/6BhBRseTkko/Vlfm8WD7oR/yzPUYyWIUpO PNvA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=sUb+EroXyapxIDNsLF15Gn1e5rtisddXEEuzUWCX6ak=; b=EeCb+ZTsdd9rX6DDNNCubis3/M59Vhp2LOIVDF8UqB25zw15ggoSwFVqOR9qhrvNb7 sNqWxR1CU9gYRIMJEwr7odb4p8OiBwwq84lSyHnVYsxzcbLdnMRVhmxsHdaAIX1K6VQ+ 9umfRb0cbyokFp7YR+4MUhsJU5JK7ad8vaqezohc/IxxMJTnGx4+mCHVkko8iLOcphqY QDDicLw1oP8lKt3ZzOUYbKECN0zkq/JIE9iiAL5yGmJ/o3CLR3F7JrbmY8cJB4KvKvTG eV6fx6b1ho5IzWOWHgh5mdUTzU6SRCOLnwrN5Zg/aAfvbpsH91XBKSt4rac/05bk2xIH oJ8A== X-Gm-Message-State: AKaTC00O6lmkcAT0CimuFMmLASY5IM9njIT0L0YTE/tqZyC95uwQu3EBC2AS0SdUUZAobPHhgsqnFIfYALwdGQ== X-Received: by 10.28.87.84 with SMTP id l81mr17509002wmb.48.1480281204989; Sun, 27 Nov 2016 13:13:24 -0800 (PST) In-Reply-To: <41b59c33-1be1-440e-a9b1-efb97c6e14a8@default> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2a00:1450:400c:c09::22f 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:209637 Archived-At: --001a11444cc46426a105424ed32e Content-Type: text/plain; charset=UTF-8 Drew Adams schrieb am Mi., 23. Nov. 2016 um 17:35 Uhr: > > >> 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. > > > > 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. > That sounds like a good approach. --001a11444cc46426a105424ed32e Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable


Drew A= dams <drew.adams@oracle.com= > schrieb am Mi., 23. Nov. 2016 um 17:35=C2=A0Uhr:
> >> 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.
>
> I agree.

Me too.=C2=A0 And definers of user-facing things, such as
defcustom and defface, do require DOC.=C2=A0 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
=C2=A0 =C2=A0they can fake it with "", which is not encouraged).<= br class=3D"gmail_msg">
2. Users of the mode should have access to the generic
=C2=A0 =C2=A0information also.=C2=A0 It should be sufficient that the
=C2=A0 =C2=A0DOC in the definition provides mode-specific information.
=C2=A0 =C2=A0It should not need to tell users general things about
=C2=A0 =C2=A0using a minor mode.
<= br>
That sounds like a good approach.
--001a11444cc46426a105424ed32e--