From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#23623: Patch to improve function options in find-func.el Date: Mon, 18 Dec 2017 18:49:56 +0200 Message-ID: <83po7coua3.fsf@gnu.org> References: <87o9oe6gt1.fsf@users.sourceforge.net> <83vah4ow8z.fsf@gnu.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1513615700 774 195.159.176.226 (18 Dec 2017 16:48:20 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 18 Dec 2017 16:48:20 +0000 (UTC) Cc: npostavs@users.sourceforge.net, 23623@debbugs.gnu.org To: rswgnu@gmail.com Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Dec 18 17:48:16 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1eQyaN-0008AR-T7 for geb-bug-gnu-emacs@m.gmane.org; Mon, 18 Dec 2017 17:48:16 +0100 Original-Received: from localhost ([::1]:55794 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eQycK-0007FI-H3 for geb-bug-gnu-emacs@m.gmane.org; Mon, 18 Dec 2017 11:50:16 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:55943) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eQyc7-0007Aa-Bv for bug-gnu-emacs@gnu.org; Mon, 18 Dec 2017 11:50:08 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eQyc6-0005gA-Kx for bug-gnu-emacs@gnu.org; Mon, 18 Dec 2017 11:50:03 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:60329) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1eQyc6-0005g2-Ib for bug-gnu-emacs@gnu.org; Mon, 18 Dec 2017 11:50:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1eQyc6-000450-AR for bug-gnu-emacs@gnu.org; Mon, 18 Dec 2017 11:50:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Dec 2017 16:50:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 23623 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 23623-submit@debbugs.gnu.org id=B23623.151361580115669 (code B ref 23623); Mon, 18 Dec 2017 16:50:02 +0000 Original-Received: (at 23623) by debbugs.gnu.org; 18 Dec 2017 16:50:01 +0000 Original-Received: from localhost ([127.0.0.1]:40777 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eQyc4-00044f-UJ for submit@debbugs.gnu.org; Mon, 18 Dec 2017 11:50:01 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:36518) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eQyc3-00044S-C1 for 23623@debbugs.gnu.org; Mon, 18 Dec 2017 11:49:59 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eQybs-0005Vn-PZ for 23623@debbugs.gnu.org; Mon, 18 Dec 2017 11:49:54 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:40268) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eQybs-0005Va-Ly; Mon, 18 Dec 2017 11:49:48 -0500 Original-Received: from [176.228.60.248] (port=1324 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1eQybs-0002gA-3I; Mon, 18 Dec 2017 11:49:48 -0500 In-reply-to: (message from Robert Weiner on Mon, 18 Dec 2017 11:24:44 -0500) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:141223 Archived-At: > From: Robert Weiner > Date: Mon, 18 Dec 2017 11:24:44 -0500 > Cc: Noam Postavsky , 23623@debbugs.gnu.org > > I often find > that I have to make the first line of docstrings long > when it involves 3 or more arguments. Is it preferable > in such cases where the text cannot be shortened enough > to discuss only some of the arguments on the first line > and document the rest afterwards? If there's no other way, yes. A better alternative is to mention all the arguments, but refrain from describing the function's effect in full, leaving the detailed description to the rest of the doc string. IOW, say only the main part in the first sentence.