From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Michael Albinus Newsgroups: gmane.emacs.devel Subject: Re: Some ideas with Emacs Date: Fri, 29 Nov 2019 21:25:48 +0100 Message-ID: <8736e6e8fn.fsf@gmx.de> References: <837e3iq0ks.fsf@gnu.org> <87h82my0fm.fsf@gmx.de> <83tv6mo4vl.fsf@gnu.org> <878snyxx5d.fsf@gmx.de> <83sgm6o2y1.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="165411"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) Cc: emacs-devel@gnu.org, stefan@marxist.se, monnier@iro.umontreal.ca, c4droid@foxmail.com To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Nov 29 21:30:01 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 1iamtt-000grn-39 for ged-emacs-devel@m.gmane.org; Fri, 29 Nov 2019 21:30:01 +0100 Original-Received: from localhost ([::1]:35026 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iamtq-0005zB-Nh for ged-emacs-devel@m.gmane.org; Fri, 29 Nov 2019 15:29:58 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:44460) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iamqB-0004nd-RA for emacs-devel@gnu.org; Fri, 29 Nov 2019 15:26:12 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iamq6-0002hJ-Lx for emacs-devel@gnu.org; Fri, 29 Nov 2019 15:26:10 -0500 Original-Received: from mout.gmx.net ([212.227.17.21]:58711) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iamq6-0002QU-Eg; Fri, 29 Nov 2019 15:26:06 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1575059152; bh=6InCb5d7iQKC0rLo9RXSHldbWQW0qq/D2XKmSU0TFqY=; h=X-UI-Sender-Class:From:To:Cc:Subject:References:Date:In-Reply-To; b=BsYk1DVyuhYP+CoannGcLPBbjhe/IelmZ985b/+R5Yv5M+aiWIisyOCdXER+D9CbE IWE7NsbKYamR6j1IBmyQV8F1IkFOj7LYy+xGIDuUSQyYvn/Z87zouywQ9ULPQ99clM Lr11xo3vYUa7Z/5OJqpxemAAo1Ydt48IknByw3Ok= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Original-Received: from detlef.gmx.de ([212.91.243.137]) by mail.gmx.com (mrgmx104 [212.227.17.168]) with ESMTPSA (Nemesis) id 1M1HZi-1idWf40qLa-002n5s; Fri, 29 Nov 2019 21:25:52 +0100 In-Reply-To: <83sgm6o2y1.fsf@gnu.org> (Eli Zaretskii's message of "Fri, 29 Nov 2019 22:14:14 +0200") X-Provags-ID: V03:K1:7uxgpOw38ByXBlP052WY0/TJdLEGX8xbqYKZ7tAWGEL2U8nuF4N zqHlh3EJwglasvhSbAeLeFlY6nkMySbdMpkxmoNt4IvpQ5majb+RX9YZz0zZsYHxoBnBtxe dGRiObkcRzJYRUfW7wApKdPJhiTT7v7MV6pbvYdNnZwi1n+aiOZlUgT97GjevG8fZ5exa2G dFMzk9W+SuRleT2s8N7Xw== X-UI-Out-Filterresults: notjunk:1;V03:K0:SgXW44DoKmQ=:SkA9s2DSEgqSTV5L6tQm0Q anIdSQJC9hBjOR+hgMMQm89ST6/EVxuYaedWDxgeTi8qdQOHSpcSnnM/XV2vcAa7jkqmH48oF 9YuiQhSA0xlTWYiZEfzHW3fB0QTmR5hqparuxhK4ynms/UEhO7OMotpMQQewbpSr2TtrMw/PP /c0Zk+for+YMuWMjgkm3hi1zeZiqZKkvI27VNiCAeDd+Rql9nUdwXZWDq6qpoaP3uzoAEguzH U4F7fVG0Vn7sbhFRUiVtY5JO81PlSUHtee8uyyTvHRkHVgVk1fVLnHLnAuNPlZPdBy/yduV3b aIXK8KEtLDPbXaAOJPGTaMoWrMstiRW9Wb2CWcAnn2kcOqMnOMWhfbzBjiUMg7jimLqItERuf vU09+EFJS99K034F8jgDEZb/kgKeUcCynqgy5VBahfW+yGChIaAsdc/Km7XyYCheKx7sh/3xy FYzXnXAZeOJh+zIwN2qcD6CiLJvZpXlETaZaU2hxwIQMViHkTVUHkm5dEw9WJsjIikOHulOxy NOnJzXM8lZbB+aZfJdbV8vYjdNOyP0oC9kfII9wYkyPECCCGWbUVI0v72aAUv1IY8CbudXvA4 n1zXif7U/jSpKzCheeZHxT7/pATSd1HLofopqlZbLM3B+rJELSxHSJ7MmEbbquwPdLOKXqf7u /bzRFpCmA9/zI4AlOWQg8GATl8XshW7lf3PuKMafUTwAWJbrchS8y1kvupNJdmIQD7IVU2HGB cOEw6QPd07wmeJywVzKkEP6SCqYdxa4ReJmKwj87FBC0ajsTaPHPzhDI7iT5GQ5BEpfJbR+a X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 212.227.17.21 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:242893 Archived-At: Eli Zaretskii writes: >> >> Personally, I don't like docstring to be too verbose. Usually, when = a >> >> function is documented with both docstrings and a manual, I prefer t= o >> >> put the examples in the manual. >> > >> > I agree: the examples should be mostly in the manual. Doc strings >> > should only have examples if it is otherwise very hard to explain >> > something. >> >> Shall we say something like this in "(elisp) Documentation Tips"? > > Not sure I understand what would you like to say there. If a function is too complex to explain it in the docstring on, say one page of ~24 lines, one shall document it more verbose in the manual. Examples, if not necessary for understanding the docstring, shall be shown in the manual. In such cases, there shall be a link to the manual in the docstring. If a function requires an exhaustive docstring, it could be an option to break it into several functions. Maybe all of this is too restrictive. But you see the intention. Best regards, Michael.