[Emacs-diffs] /srv/bzr/emacs/trunk r105024: Doc fixes for thingatpt.el.

[Chong Yidong]

------------------------------------------------------------
revno: 105024
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Thu 2011-07-07 14:31:57 -0400
message:
  Doc fixes for thingatpt.el.
  
  * lisp/thingatpt.el (forward-thing, bounds-of-thing-at-point)
  (thing-at-point, beginning-of-thing, end-of-thing, in-string-p)
  (end-of-sexp, beginning-of-sexp)
  (thing-at-point-bounds-of-list-at-point, forward-whitespace)
  (forward-symbol, forward-same-syntax, word-at-point)
  (sentence-at-point): Doc fix (Bug#1144).
modified:
  lisp/ChangeLog
  lisp/thingatpt.el

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2011-07-07 18:28:25 +0000
+++ b/lisp/ChangeLog    2011-07-07 18:31:57 +0000
@@ -1,3 +1,12 @@
+2011-07-07  Chong Yidong  <address@hidden>
+
+       * thingatpt.el (forward-thing, bounds-of-thing-at-point)
+       (thing-at-point, beginning-of-thing, end-of-thing, in-string-p)
+       (end-of-sexp, beginning-of-sexp)
+       (thing-at-point-bounds-of-list-at-point, forward-whitespace)
+       (forward-symbol, forward-same-syntax, word-at-point)
+       (sentence-at-point): Doc fix (Bug#1144).
+
 2011-07-07  Lars Magne Ingebrigtsen  <address@hidden>
 
        * info.el (Info-mode-map): Remove S-TAB binding, since [backtab]

=== modified file 'lisp/thingatpt.el'
--- a/lisp/thingatpt.el 2011-06-30 02:04:32 +0000
+++ b/lisp/thingatpt.el 2011-07-07 18:31:57 +0000
@@ -55,7 +55,11 @@
 
 ;;;###autoload
 (defun forward-thing (thing &optional n)
-  "Move forward to the end of the Nth next THING."
+  "Move forward to the end of the Nth next THING.
+THING should be a symbol specifying a type of syntactic entity.
+Possibilities include `symbol', `list', `sexp', `defun',
+`filename', `url', `email', `word', `sentence', `whitespace',
+`line', and `page'."
   (let ((forward-op (or (get thing 'forward-op)
                        (intern-soft (format "forward-%s" thing)))))
     (if (functionp forward-op)
@@ -67,15 +71,16 @@
 ;;;###autoload
 (defun bounds-of-thing-at-point (thing)
   "Determine the start and end buffer locations for the THING at point.
-THING is a symbol which specifies the kind of syntactic entity you want.
-Possibilities include `symbol', `list', `sexp', `defun', `filename', `url',
-`email', `word', `sentence', `whitespace', `line', `page' and others.
-
-See the file `thingatpt.el' for documentation on how to define
-a symbol as a valid THING.
-
-The value is a cons cell (START . END) giving the start and end positions
-of the textual entity that was found."
+THING should be a symbol specifying a type of syntactic entity.
+Possibilities include `symbol', `list', `sexp', `defun',
+`filename', `url', `email', `word', `sentence', `whitespace',
+`line', and `page'.
+
+See the file `thingatpt.el' for documentation on how to define a
+valid THING.
+
+Return a cons cell (START . END) giving the start and end
+positions of the thing found."
   (if (get thing 'bounds-of-thing-at-point)
       (funcall (get thing 'bounds-of-thing-at-point))
     (let ((orig (point)))
@@ -125,9 +130,10 @@
 ;;;###autoload
 (defun thing-at-point (thing)
   "Return the THING at point.
-THING is a symbol which specifies the kind of syntactic entity you want.
-Possibilities include `symbol', `list', `sexp', `defun', `filename', `url',
-`email', `word', `sentence', `whitespace', `line', `page' and others.
+THING should be a symbol specifying a type of syntactic entity.
+Possibilities include `symbol', `list', `sexp', `defun',
+`filename', `url', `email', `word', `sentence', `whitespace',
+`line', and `page'.
 
 See the file `thingatpt.el' for documentation on how to define
 a symbol as a valid THING."
@@ -140,11 +146,15 @@
 ;; Go to beginning/end
 
 (defun beginning-of-thing (thing)
+  "Move point to the beginning of THING.
+The bounds of THING are determined by `bounds-of-thing-at-point'."
   (let ((bounds (bounds-of-thing-at-point thing)))
     (or bounds (error "No %s here" thing))
     (goto-char (car bounds))))
 
 (defun end-of-thing (thing)
+  "Move point to the end of THING.
+The bounds of THING are determined by `bounds-of-thing-at-point'."
   (let ((bounds (bounds-of-thing-at-point thing)))
     (or bounds (error "No %s here" thing))
     (goto-char (cdr bounds))))
@@ -162,12 +172,16 @@
 ;;  Sexps
 
 (defun in-string-p ()
+  "Return non-nil if point is in a string.
+\[This is an internal function.]"
   (let ((orig (point)))
     (save-excursion
       (beginning-of-defun)
       (nth 3 (parse-partial-sexp (point) orig)))))
 
 (defun end-of-sexp ()
+  "Move point to the end of the current sexp.
+\[This is an internal function.]"
   (let ((char-syntax (char-syntax (char-after))))
     (if (or (eq char-syntax ?\))
            (and (eq char-syntax ?\") (in-string-p)))
@@ -177,6 +191,8 @@
 (put 'sexp 'end-op 'end-of-sexp)
 
 (defun beginning-of-sexp ()
+  "Move point to the beginning of the current sexp.
+\[This is an internal function.]"
   (let ((char-syntax (char-syntax (char-before))))
     (if (or (eq char-syntax ?\()
            (and (eq char-syntax ?\") (in-string-p)))
@@ -190,6 +206,8 @@
 (put 'list 'bounds-of-thing-at-point 'thing-at-point-bounds-of-list-at-point)
 
 (defun thing-at-point-bounds-of-list-at-point ()
+  "Return the bounds of the list at point.
+\[Internal function used by `bounds-of-thing-at-point'.]"
   (save-excursion
     (let ((opoint (point))
          (beg (condition-case nil
@@ -397,6 +415,11 @@
 ;;  Whitespace
 
 (defun forward-whitespace (arg)
+  "Move point to the end of the next sequence of whitespace chars.
+Each such sequence may be a single newline, or a sequence of
+consecutive space and/or tab characters.
+With prefix argument ARG, do it ARG times if positive, or move
+backwards ARG times if negative."
   (interactive "p")
   (if (natnump arg)
       (re-search-forward "[ \t]+\\|\n" nil 'move arg)
@@ -414,6 +437,11 @@
 ;;  Symbols
 
 (defun forward-symbol (arg)
+  "Move point to the next position that is the end of a symbol.
+A symbol is any sequence of characters that are in either the
+word constituent or symbol constituent syntax class.
+With prefix argument ARG, do it ARG times if positive, or move
+backwards ARG times if negative."
   (interactive "p")
   (if (natnump arg)
       (re-search-forward "\\(\\sw\\|\\s_\\)+" nil 'move arg)
@@ -425,6 +453,9 @@
 ;;  Syntax blocks
 
 (defun forward-same-syntax (&optional arg)
+  "Move point past all characters with the same syntax class.
+With prefix argument ARG, do it ARG times if positive, or move
+backwards ARG times if negative."
   (interactive "p")
   (while (< arg 0)
     (skip-syntax-backward
@@ -436,8 +467,13 @@
 
 ;;  Aliases
 
-(defun word-at-point () (thing-at-point 'word))
-(defun sentence-at-point () (thing-at-point 'sentence))
+(defun word-at-point ()
+  "Return the word at point.  See `thing-at-point'."
+  (thing-at-point 'word))
+
+(defun sentence-at-point ()
+  "Return the sentence at point.  See `thing-at-point'."
+  (thing-at-point 'sentence))
 
 (defun read-from-whole-string (str)
   "Read a Lisp expression from STR.