From unknown Fri Aug 15 15:56:20 2025 X-Loop: help-debbugs@gnu.org Subject: bug#8098: 24.0.50; Doc strings in `image-mode.el' Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 22 Feb 2011 21:43:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 8098 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 8098@debbugs.gnu.org X-Debbugs-Original-To: Received: via spool by submit@debbugs.gnu.org id=B.129841095925695 (code B ref -1); Tue, 22 Feb 2011 21:43:01 +0000 Received: (at submit) by debbugs.gnu.org; 22 Feb 2011 21:42:39 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Ps00E-0006gO-3A for submit@debbugs.gnu.org; Tue, 22 Feb 2011 16:42:38 -0500 Received: from eggs.gnu.org ([140.186.70.92]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Ps00C-0006gE-Je for submit@debbugs.gnu.org; Tue, 22 Feb 2011 16:42:37 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Ps006-0003eK-G8 for submit@debbugs.gnu.org; Tue, 22 Feb 2011 16:42:31 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-4.2 required=5.0 tests=BAYES_00,RCVD_IN_DNSWL_MED, T_RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 Received: from lists.gnu.org ([199.232.76.165]:60927) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Ps006-0003eB-9B for submit@debbugs.gnu.org; Tue, 22 Feb 2011 16:42:30 -0500 Received: from [140.186.70.92] (port=48566 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Ps005-0007aJ-1L for bug-gnu-emacs@gnu.org; Tue, 22 Feb 2011 16:42:30 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Ps003-0003dA-PX for bug-gnu-emacs@gnu.org; Tue, 22 Feb 2011 16:42:28 -0500 Received: from rcsinet10.oracle.com ([148.87.113.121]:31752) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Ps003-0003cZ-HW for bug-gnu-emacs@gnu.org; Tue, 22 Feb 2011 16:42:27 -0500 Received: from rcsinet15.oracle.com (rcsinet15.oracle.com [148.87.113.117]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id p1MLgPpR026076 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Tue, 22 Feb 2011 21:42:26 GMT Received: from acsmt353.oracle.com (acsmt353.oracle.com [141.146.40.153]) by rcsinet15.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id p1MLgKvR024100 for ; Tue, 22 Feb 2011 21:42:21 GMT Received: from abhmt014.oracle.com by acsmt355.oracle.com with ESMTP id 1077186541298410892; Tue, 22 Feb 2011 13:41:32 -0800 Received: from dradamslap1 (/10.159.61.196) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 22 Feb 2011 13:41:32 -0800 From: "Drew Adams" Date: Tue, 22 Feb 2011 13:41:34 -0800 Message-ID: <182F64DCED08445BAEC0DDD98398BE24@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcvS2UZPPdJQOjQQT7Gg7QWGXWAprQ== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5994 X-Source-IP: acsmt353.oracle.com [141.146.40.153] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090206.4D642DC0.0218:SCFMA4539814,ss=1,fgs=0 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 199.232.76.165 X-Spam-Score: -6.4 (------) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.4 (------) Consider adding more doc strings - there is a paucity of them in this file. Remove the second line of the `image-type' doc string - we don't normally document the _use_ of a variable (since it could be used for more than one thing). Why "as text" in the doc string of `image-minor-mode-map' but not that of `image-mode-map'? Is that correct? Maybe it is, in which case the minor mode is poorly named. The names indicate that they are the same thing, one major the other minor. `image-toggle-display-text' is a _toggle_, so its doc string's first line should not say that it shows the file as text. It should say that it toggles showing the file as text (or some such). Similarly for `image-toggle-display-image'? And `image-toggle-display'? (It's unclear from the doc strings what this is all about. Why three commands?) Why is this function named `*-hook': `image-after-revert-hook'? Why not just `image-after-revert'? This is not a hook (a variable); it is a hook function. Doc string of `image-transform-mode' is grammatically incorrect: "transforming the view of images Image modetransforming the view of images Image mode". Capitalize and spell-check the doc string of `image-transform-mode'. And say a bit more (scaling and rotating what?). `image-transform-resize', `image-transform-properties', and `image-transform-set-resize': Doc string first line is not standalone (incomplete sentence). In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600) of 2011-02-14 on 3249CTO Windowing system distributor `Microsoft Corp.', version 5.1.2600 configured using `configure --with-gcc (4.4) --no-opt --cflags -Ic:/imagesupport/include' From unknown Fri Aug 15 15:56:20 2025 X-Loop: help-debbugs@gnu.org Subject: bug#8098: 24.0.50; Doc strings in `image-mode.el' Resent-From: Chong Yidong Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 09 Apr 2011 20:31:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 8098 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "Drew Adams" Cc: 8098@debbugs.gnu.org Received: via spool by 8098-submit@debbugs.gnu.org id=B8098.130238105314732 (code B ref 8098); Sat, 09 Apr 2011 20:31:02 +0000 Received: (at 8098) by debbugs.gnu.org; 9 Apr 2011 20:30:53 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Q8eo1-0003pZ-FL for submit@debbugs.gnu.org; Sat, 09 Apr 2011 16:30:53 -0400 Received: from vm-emlprdomr-05.its.yale.edu ([130.132.50.146]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Q8enz-0003pM-JH for 8098@debbugs.gnu.org; Sat, 09 Apr 2011 16:30:52 -0400 Received: from furball ([64.134.240.70]) (authenticated bits=0) by vm-emlprdomr-05.its.yale.edu (8.14.4/8.14.4) with ESMTP id p39KUjDq032483 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Sat, 9 Apr 2011 16:30:46 -0400 Received: by furball (Postfix, from userid 1000) id 4AD0C1602E5; Sat, 9 Apr 2011 16:30:46 -0400 (EDT) From: Chong Yidong References: <182F64DCED08445BAEC0DDD98398BE24@us.oracle.com> Date: Sat, 09 Apr 2011 16:30:46 -0400 In-Reply-To: <182F64DCED08445BAEC0DDD98398BE24@us.oracle.com> (Drew Adams's message of "Tue, 22 Feb 2011 13:41:34 -0800") Message-ID: <87mxjznp55.fsf@stupidchicken.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Scanned-By: MIMEDefang 2.71 on 130.132.50.146 X-Spam-Score: -2.6 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.6 (--) "Drew Adams" writes: > `image-toggle-display-text' is a _toggle_, so its doc string's first > line should not say that it shows the file as text. It should say that > it toggles showing the file as text (or some such). Similarly for > `image-toggle-display-image'? These functions don't toggle. They are helper functions for image-toggle-display and co. I've cleaned up the other documentation problems you pointed out. Thanks. From debbugs-submit-bounces@debbugs.gnu.org Sat Apr 09 16:31:06 2011 Received: (at control) by debbugs.gnu.org; 9 Apr 2011 20:31:06 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Q8eoD-0003qF-LD for submit@debbugs.gnu.org; Sat, 09 Apr 2011 16:31:05 -0400 Received: from vm-emlprdomr-03.its.yale.edu ([130.132.50.144]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Q8eoB-0003pj-VK for control@debbugs.gnu.org; Sat, 09 Apr 2011 16:31:04 -0400 Received: from furball ([64.134.240.70]) (authenticated bits=0) by vm-emlprdomr-03.its.yale.edu (8.14.4/8.14.4) with ESMTP id p39KUwU5006656 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT) for ; Sat, 9 Apr 2011 16:30:58 -0400 Received: by furball (Postfix, from userid 1000) id 287AF1602E5; Sat, 9 Apr 2011 16:30:59 -0400 (EDT) From: Chong Yidong To: control@debbugs.gnu.org Subject: close 8098 Date: Sat, 09 Apr 2011 16:30:58 -0400 Message-ID: <87sjtrcgl9.fsf@stupidchicken.com> MIME-Version: 1.0 Content-Type: text/plain X-Scanned-By: MIMEDefang 2.71 on 130.132.50.144 X-Spam-Score: -2.6 (--) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.6 (--) close 8098 thanks From unknown Fri Aug 15 15:56:20 2025 X-Loop: help-debbugs@gnu.org Subject: bug#8098: 24.0.50; Doc strings in `image-mode.el' Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 09 Apr 2011 20:38:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 8098 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "'Chong Yidong'" Cc: 8098@debbugs.gnu.org Received: via spool by 8098-submit@debbugs.gnu.org id=B8098.130238143415496 (code B ref 8098); Sat, 09 Apr 2011 20:38:02 +0000 Received: (at 8098) by debbugs.gnu.org; 9 Apr 2011 20:37:14 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Q8euA-00041s-6o for submit@debbugs.gnu.org; Sat, 09 Apr 2011 16:37:14 -0400 Received: from rcsinet10.oracle.com ([148.87.113.121]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Q8eu8-00041Z-Fe for 8098@debbugs.gnu.org; Sat, 09 Apr 2011 16:37:12 -0400 Received: from rcsinet13.oracle.com (rcsinet13.oracle.com [148.87.113.125]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id p39Kb4PJ022376 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 9 Apr 2011 20:37:06 GMT Received: from acsmt357.oracle.com (acsmt357.oracle.com [141.146.40.157]) by rcsinet13.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id p39Kb4MM008121 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sat, 9 Apr 2011 20:37:04 GMT Received: from abhmt009.oracle.com (abhmt009.oracle.com [141.146.116.18]) by acsmt357.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p39Kb4P7003201; Sat, 9 Apr 2011 15:37:04 -0500 Received: from dradamslap1 (/10.159.37.106) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sat, 09 Apr 2011 13:37:03 -0700 From: "Drew Adams" References: <182F64DCED08445BAEC0DDD98398BE24@us.oracle.com> <87mxjznp55.fsf@stupidchicken.com> Date: Sat, 9 Apr 2011 13:37:06 -0700 Message-ID: <5CB35F97DF1C487E97611B5EAFB6BA00@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-reply-to: <87mxjznp55.fsf@stupidchicken.com> X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5994 Thread-Index: Acv29QaySvn4enJASH6t+QKXrhiCswAAI4Hg X-Source-IP: acsmt357.oracle.com [141.146.40.157] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090203.4DA0C370.004F:SCFSTAT5015188,ss=1,fgs=0 X-Spam-Score: -6.5 (------) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.5 (------) > > `image-toggle-display-text' ... `image-toggle-display-image'? > > These functions don't toggle. They are helper functions for > image-toggle-display and co. Oh, right. OK, but in that case we could have better names for them. Maybe consider using Stefan's `*--*' convention for "internal" functions here. I.e., `image-toggle-display--text', `image-toggle-display--image' > I've cleaned up the other documentation problems you pointed out. Thx.