bug#24734: [PATCH] Minor improvement of the doc of lisp/paren.el.

bug#24734: [PATCH] Minor improvement of the doc of lisp/paren.el.

[Hong Xu]

---

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

bug#24734: [PATCH] Minor improvement of the doc of lisp/paren.el.

[Thien-Thi Nguyen]

[-- Attachment #1: Type: text/plain, Size: 650 bytes --]


() Hong Xu <hong@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


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

bug#24734: Minor improvement of the doc of lisp/paren.el

[Hong Xu]

[-- Attachment #1: Type: text/plain, Size: 56 bytes --]


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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 818 bytes --]

bug#24734: Minor improvement of the doc of lisp/paren.el

[Hong Xu]

[-- Attachment #1.1: Type: text/plain, Size: 107 bytes --]


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

The attachment is an updated version.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: paren.patch --]
[-- Type: text/x-diff, Size: 870 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 818 bytes --]

bug#24734: Minor improvement of the doc of lisp/paren.el

[npostavs]

tags 24734 fixed
close 24734 25.2
quit

Hong Xu <hong@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.