GNU bug report logs - #24734
[PATCH] Minor improvement of the doc of lisp/paren.el.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 24734 in the body.
You can then email your comments to 24734 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Hong Xu <hong <at> topbug.net>
To: bug-gnu-emacs <at> gnu.org
Cc: Hong Xu <hong <at> topbug.net>
Subject: [PATCH] Minor improvement of the doc of lisp/paren.el.
Date: Tue, 18 Oct 2016 13:16:58 -0700

---

These are my suggested imporvements of the docs in lisp/paren.el, after
I looked into the code for the first time.

---
 lisp/paren.el | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lisp/paren.el b/lisp/paren.el
index 53eb50077f25..f0df1ff2ea4d 100644
--- a/lisp/paren.el
+++ b/lisp/paren.el
@@ -181,6 +181,7 @@ show-paren-data-function
 Where HERE-BEG..HERE-END is expected to be near point.")
 
 (defun show-paren--default ()
+  "The default value of `show-paren-data-function'."
   (let* ((temp (show-paren--locate-near-paren))
 	 (dir (car temp))
 	 (outside (cdr temp))
@@ -233,9 +234,8 @@ show-paren--default
 		  (if (= dir 1) pos (1+ pos))
 		  mismatch)))))))
 
-;; Find the place to show, if there is one,
-;; and show it until input arrives.
 (defun show-paren-function ()
+  "Highlight the parentheses until the next input arrives."
   (let ((data (and show-paren-mode (funcall show-paren-data-function))))
     (if (not data)
         (progn
-- 
2.1.4

Message #8 received at 24734 <at> debbugs.gnu.org (full text, mbox):

From: Thien-Thi Nguyen <ttn <at> gnu.org>
To: Hong Xu <hong <at> topbug.net>
Cc: 24734 <at> debbugs.gnu.org
Subject: Re: bug#24734: [PATCH] Minor improvement of the doc of lisp/paren.el.
Date: Wed, 19 Oct 2016 10:06:10 +0200

[Message part 1 (text/plain, inline)]

() Hong Xu <hong <at> topbug.net>
() Tue, 18 Oct 2016 13:16:58 -0700

    (defun show-paren--default ()
   +  "The default value of `show-paren-data-function'."

It's better to describe what the function does, first.  Where
and how it is used is secondary.  (It's no problem to refer to
‘show-paren-data-function’, if it follows the description.)

-- 
Thien-Thi Nguyen -----------------------------------------------
 (defun responsep (type via)
   (case type
     (technical (eq 'mailing-list via))
     ...))                              748E A0E8 1CB8 A748 9BFA
--------------------------------------- 6CE4 6703 2224 4C80 7502

[signature.asc (application/pgp-signature, inline)]

Message #11 received at 24734 <at> debbugs.gnu.org (full text, mbox):

From: Hong Xu <hong <at> topbug.net>
To: 24734 <at> debbugs.gnu.org
Subject: Minor improvement of the doc of lisp/paren.el
Date: Tue, 25 Oct 2016 13:39:34 -0700

[Message part 1 (text/plain, inline)]

Can we push this minor fix? This is a really easy fix.

[signature.asc (application/pgp-signature, inline)]

Message #14 received at 24734 <at> debbugs.gnu.org (full text, mbox):

From: Hong Xu <hong <at> topbug.net>
To: 24734 <at> debbugs.gnu.org
Subject: Re: Minor improvement of the doc of lisp/paren.el
Date: Wed, 02 Nov 2016 12:06:12 -0700

[Message part 1 (text/plain, inline)]

OK, actually I never received the response email, don't know why.

The attachment is an updated version.

[paren.patch (text/x-diff, inline)]

diff --git a/lisp/paren.el b/lisp/paren.el
index 53eb50077f25..100cc58f0cbe 100644
--- a/lisp/paren.el
+++ b/lisp/paren.el
@@ -181,6 +181,9 @@ show-paren-data-function
 Where HERE-BEG..HERE-END is expected to be near point.")
 
 (defun show-paren--default ()
+  "Finds the opener/closer near point and its match.
+
+It is the default value of `show-paren-data-function'."
   (let* ((temp (show-paren--locate-near-paren))
 	 (dir (car temp))
 	 (outside (cdr temp))
@@ -233,9 +236,8 @@ show-paren--default
 		  (if (= dir 1) pos (1+ pos))
 		  mismatch)))))))
 
-;; Find the place to show, if there is one,
-;; and show it until input arrives.
 (defun show-paren-function ()
+  "Highlight the parentheses until the next input arrives."
   (let ((data (and show-paren-mode (funcall show-paren-data-function))))
     (if (not data)
         (progn

[signature.asc (application/pgp-signature, inline)]

Message #17 received at 24734 <at> debbugs.gnu.org (full text, mbox):

From: npostavs <at> users.sourceforge.net
To: Hong Xu <hong <at> topbug.net>
Cc: 24734 <at> debbugs.gnu.org
Subject: Re: bug#24734: Minor improvement of the doc of lisp/paren.el
Date: Tue, 14 Mar 2017 00:08:24 -0400

tags 24734 fixed
close 24734 25.2
quit

Hong Xu <hong <at> topbug.net> writes:

>
> The attachment is an updated version.

Pushed to emacs-25 [1: 6de8429c29].

1: 2017-03-14 00:07:14 -0400 6de8429c2989d0fccab0a485c7f28e522e07fa92
  * lisp/paren.el (show-paren--default, show-paren-function): Add docstring.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.