From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Noam Postavsky Newsgroups: gmane.emacs.bugs Subject: bug#29328: 24.5; doc string of `transpose-subr` Date: Fri, 17 Nov 2017 10:23:24 -0500 Message-ID: References: <2b3492ed-c7ab-433b-a8ff-3de3c5f38c62@default> <83shddggqe.fsf@gnu.org> <93f79e75-eac2-406c-b483-5bf60020a7e4@default> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" X-Trace: blaine.gmane.org 1510932260 6121 195.159.176.226 (17 Nov 2017 15:24:20 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 17 Nov 2017 15:24:20 +0000 (UTC) Cc: 29328@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Nov 17 16:24:15 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 1eFiV1-00012l-4n for geb-bug-gnu-emacs@m.gmane.org; Fri, 17 Nov 2017 16:24:11 +0100 Original-Received: from localhost ([::1]:46459 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eFiV8-0002jA-C7 for geb-bug-gnu-emacs@m.gmane.org; Fri, 17 Nov 2017 10:24:18 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38804) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eFiUw-0002is-OX for bug-gnu-emacs@gnu.org; Fri, 17 Nov 2017 10:24:10 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eFiUs-0007lu-6k for bug-gnu-emacs@gnu.org; Fri, 17 Nov 2017 10:24:06 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:36478) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1eFiUs-0007lf-2J for bug-gnu-emacs@gnu.org; Fri, 17 Nov 2017 10:24:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1eFiUr-0001hG-PJ for bug-gnu-emacs@gnu.org; Fri, 17 Nov 2017 10:24:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Noam Postavsky Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 17 Nov 2017 15:24:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 29328 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 29328-submit@debbugs.gnu.org id=B29328.15109322136484 (code B ref 29328); Fri, 17 Nov 2017 15:24:01 +0000 Original-Received: (at 29328) by debbugs.gnu.org; 17 Nov 2017 15:23:33 +0000 Original-Received: from localhost ([127.0.0.1]:45159 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFiUP-0001gV-1m for submit@debbugs.gnu.org; Fri, 17 Nov 2017 10:23:33 -0500 Original-Received: from mail-wm0-f51.google.com ([74.125.82.51]:41431) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFiUN-0001gF-EQ for 29328@debbugs.gnu.org; Fri, 17 Nov 2017 10:23:32 -0500 Original-Received: by mail-wm0-f51.google.com with SMTP id b189so7196373wmd.0 for <29328@debbugs.gnu.org>; Fri, 17 Nov 2017 07:23:31 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:sender:in-reply-to:references:from:date:message-id :subject:to:cc; bh=8FgG5mb5fjJouB1qNkWBS+e8ylxQmI8zpjTXlfaaWbk=; b=M7Hkv+Q1pU7iAiGNt1UoJ59l8kHMHe2eBwJ6+HcsntvhIFLrhnyjbbVxA8nUgXUbri ujHo3UzPKqEQRuo+KMPCCdL6XNJnV3sHyEF9vZ4zLZV6jeEf7+X1aWLZSrT0t21+5tqg SvWVgD2b/66WSMg73HGngq6XpAlBUSpUogGRztCNnA2SWXmnOLXbkd4BvtcKSycglnK9 2CF1EqhfxowTjw6aiqIAClu+iilNCLb1MHjhvr6FNQkuAYpulUHV+Ni2YGxbiAyEBjze 8CCtrGlR/WuPcT/UtmyrQXkx2KosABDxKrSrFRHndONix6HLtc0kTYkn+QQaPjs2hkZo Yutw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:sender:in-reply-to:references:from :date:message-id:subject:to:cc; bh=8FgG5mb5fjJouB1qNkWBS+e8ylxQmI8zpjTXlfaaWbk=; b=fbr7jLhFayUKow1Wg7NGjF5r9UQY3qEM/95fDkhvlnD6LReL5QY4QQTiBxbxrQeadN g5Cxsd+0LMc0fNOrGelARAIdriaq2MkgxLfoAak491fSWygt90jXwllCYpc0qW7eZm4P qd6NgFhuK2wNyOdtpm68fNmWtD69400Er1RTpvIj25NR3mcojKzI1TQY+lKyW2tSBCdV FkibpJe5tsaUr51yCFujrl5rABUr9rYWNitUie5sjiQrqkvFCZ6souiRIAYbU3vSli3E IBPq7dAkt7VrDviaLBG9e6/SxxK2wzd6upeIZKTMcGn7KD7BhyF9jD1YlMkgej6OXEp1 eiYg== X-Gm-Message-State: AJaThX7e5KxQBQ7OBr+jqU+99FtLLEGeS0C5mDblW/Bd6ZBeuHuwfMyI oYoByoES9zEm+LfHQGxgyz+Q2mLd03EK9WGuiQU= X-Google-Smtp-Source: AGs4zMZ/Yo2RmUk1pgHbvD5CUJ0Wd7wV0utfJ9oHzvVT3MkvHENFKWbG4H68VHlwVupU91W270bPK36qnxtjyPi+Dec= X-Received: by 10.28.247.15 with SMTP id v15mr4276642wmh.152.1510932205447; Fri, 17 Nov 2017 07:23:25 -0800 (PST) Original-Received: by 10.223.151.116 with HTTP; Fri, 17 Nov 2017 07:23:24 -0800 (PST) In-Reply-To: <93f79e75-eac2-406c-b483-5bf60020a7e4@default> X-Google-Sender-Auth: O4anEdTJjt3qXir-wEt9VLmAN6I 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:140010 Archived-At: On Fri, Nov 17, 2017 at 10:02 AM, Drew Adams wrote: >> > The doc string should describe each parameter. Parameter SPECIAL is >> > not described, and its name is not specific or enlightening. >> >> I don't see how it can be meaningfully documented. > > That's tantamount to saying that the parameter has no meaning, > no behavior. If it does something then that something should > be describable, in some way, at least. The place to start is > with the intention - why do we have such a parameter? What > does it let you do? Why/when would code ever make use of it? How about something like this: --- i/lisp/simple.el +++ w/lisp/simple.el @@ -6951,7 +6951,9 @@ transpose-subr "Subroutine to do the work of transposing objects. Works for lines, sentences, paragraphs, etc. MOVER is a function that moves forward by units of the given object (e.g. forward-sentence, -forward-paragraph). If ARG is zero, exchanges the current object +forward-paragraph). If SPECIAL is non-nil, then MOVER should +return the bounds of the object as a cons (BEG . END) instead. +If ARG is zero, exchanges the current object with the one containing mark. If ARG is an integer, moves the current object past ARG following (if ARG is positive) or preceding (if ARG is negative) objects, leaving point after the