From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Yuan Fu Newsgroups: gmane.emacs.devel Subject: Re: Adding examples in the doc (was: Some ideas with Emacs) Date: Fri, 29 Nov 2019 14:30:51 -0500 Message-ID: <8D5852C4-2481-4636-B0B2-42ADC1F42D34@gmail.com> References: <837e3iq0ks.fsf@gnu.org> <87h82my0fm.fsf@gmx.de> Mime-Version: 1.0 (Mac OS X Mail 13.0 \(3601.0.10\)) Content-Type: multipart/alternative; boundary="Apple-Mail=_DC42CC88-3095-49BB-BB1A-35F0D9524372" Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="189581"; mail-complaints-to="usenet@blaine.gmane.org" Cc: Stefan Kangas , Eli Zaretskii , Michael Albinus , Anonymous , Emacs developers To: Stefan Monnier Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Nov 29 20:31:49 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.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1ialzY-000nAv-Nq for ged-emacs-devel@m.gmane.org; Fri, 29 Nov 2019 20:31:48 +0100 Original-Received: from localhost ([::1]:34818 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ialzX-00054u-DX for ged-emacs-devel@m.gmane.org; Fri, 29 Nov 2019 14:31:47 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:60317) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ialyx-00053V-OQ for emacs-devel@gnu.org; Fri, 29 Nov 2019 14:31:12 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ialyq-00057y-Py for emacs-devel@gnu.org; Fri, 29 Nov 2019 14:31:07 -0500 Original-Received: from mail-qk1-x72e.google.com ([2607:f8b0:4864:20::72e]:46680) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1ialyo-0004rE-Am; Fri, 29 Nov 2019 14:31:02 -0500 Original-Received: by mail-qk1-x72e.google.com with SMTP id f5so8084097qkm.13; Fri, 29 Nov 2019 11:30:55 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:message-id:mime-version:subject:date:in-reply-to:cc:to :references; bh=NI76NdVis/RkkfCy/0K9G3jpwzmoZ9gMN5t+GzxXqBI=; b=L2QJKpTSZCCJIjhofliQ43K110kXx7dHRKVl07A5Nx6+RJD3kciJ5DSoo6XBFMzvvF WvGddysB+K2sWF3S0h+pdQW8fWy47qnOZVLxseEwGKwffQIOfIPIiCCXjuGfzW2BwmT2 bUnAIEVF8DhEHi9XKMMxpzXj29D2XMxbK+BAg4ui2WWMI6uFGOggTPkEJXKcpYsAqwVt 61z5/2wyHDrm82cZMZs1+NR9WQEbTZ+/pTC/CdoiABHVCO0bRGh4O2KSlyBGQxU4LXC0 2mRswXa40V43bGi+4KBndDe2SxBmZBIiFteqw8ODjms0FpCoTlrESMS2XIFwp29+U14C +SIA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:message-id:mime-version:subject:date :in-reply-to:cc:to:references; bh=NI76NdVis/RkkfCy/0K9G3jpwzmoZ9gMN5t+GzxXqBI=; b=t5J/u9K/UUxbqhRojVejylj+u7RzxZj2q9X5GDvosqTdElc80iXardcOTRqCxRmNCJ CSZ59kD4+OkEeKZW37k1FwVBvJdXXLiHdyZCjrmc47XcAW8B3RAGiipxqQg4f8DU6Qqj MdjGMSGOtFlXIaXdSHaptRThYs9Fbgl4+B3I44X7dgX72W+B7YAXL8P9csDhB8Z7BsM5 95Rlt5q8P4I/DVFJzm1Cm4vwPsT5d2zRb/UdN0sMCOqui4jk/1S5tKrWmS+usF6zatqB VPBGB7xRd/ksYZgram/FMqQqoyOEKaRfcALHltf18JQ02HwboqO0i22K+KlLhxXqcVfr +OIQ== X-Gm-Message-State: APjAAAVIuto9smJCVUFf8AH2cdc9BgbeNqTFEZzx73A/xzdkPH8gE/AP tdBhM5Fum8Hc+mC4Kg7/JvR/InpfLrg= X-Google-Smtp-Source: APXvYqyr1+nhpjogeW2Nm95gYURDtnu5krbCxtR90ACblnksGKNbE6B/2QOyDoauoG66KmqyMymxMw== X-Received: by 2002:ae9:f50a:: with SMTP id o10mr18308550qkg.143.1575055854748; Fri, 29 Nov 2019 11:30:54 -0800 (PST) Original-Received: from ?IPv6:2601:98a:4102:4770:54fa:b259:8a8e:60ab? ([2601:98a:4102:4770:54fa:b259:8a8e:60ab]) by smtp.gmail.com with ESMTPSA id 11sm11964886qtx.45.2019.11.29.11.30.53 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 29 Nov 2019 11:30:54 -0800 (PST) In-Reply-To: X-Mailer: Apple Mail (2.3601.0.10) X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2607:f8b0:4864:20::72e 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.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:242887 Archived-At: --Apple-Mail=_DC42CC88-3095-49BB-BB1A-35F0D9524372 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=us-ascii >>> AFACT, currently we have some examples in the Elisp manual and very >>> few examples in docstrings. >>> It might be a good idea to encourage the addition of examples either = in >>> docstrings or in the Elisp manual (or both). >> Personally, I don't like docstring to be too verbose. >=20 > I tend to agree. Of course part of it is that a verbose docstring is = an > indication that the function is complex to use, but there's also = simply > the impact on the visual distance between the function header and the = code. FYI there is a package that does similar things: = https://github.com/xuchunyang/elisp-demos = Yuan= --Apple-Mail=_DC42CC88-3095-49BB-BB1A-35F0D9524372 Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset=us-ascii
AFACT, currently we have some examples in the Elisp manual = and very
few examples in docstrings.
It = might be a good idea to encourage the addition of examples either in
docstrings or in the Elisp manual (or both).
Personally, I don't like docstring to be too = verbose.

I tend to agree. =  Of course part of it is that a verbose docstring is an
indication that the function is complex to use, but there's = also simply
the impact on the visual distance between the = function header and the code.

FYI there is a package that does similar things: https://github.com/xuchunyang/elisp-demos

Yuan
= --Apple-Mail=_DC42CC88-3095-49BB-BB1A-35F0D9524372--