mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-09 07:40:39 -08:00
Code Issues Projects Releases Wiki Activity

(emacs-lisp-docstring-fill-column): New custom variable.

Browse source 
(lisp-fill-paragraph): Use it.  Add ?, to `paragraph-separate' so
that first docstring lines ending with a comma are respected.  Add
"`(" to same so that function and macro bodies beginning with a
backquote do not get disturbed.  Revise the comments.
This commit is contained in:
Matthew Swift 2003-03-02 16:18:36 +00:00
parent 58e91b7793
commit 3e8737bf4c
1 changed files with 42 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

54
lisp/emacs-lisp/lisp-mode.el
View file

@ -1055,26 +1055,56 @@ ENDPOS is encountered."
;;;; Lisp paragraph filling commands. ;;;; Lisp paragraph filling commands.
(defcustom emacs-lisp-docstring-fill-column 65
"Value of `fill-column' to use when filling a docstring.
Any non-integer value means do not use a different value of
`fill-column' when filling docstrings."
:type '(choice (integer)
(const :tag "Use the current `fill-column'" t))
:group 'lisp)
(defun lisp-fill-paragraph (&optional justify) (defun lisp-fill-paragraph (&optional justify)
"Like \\[fill-paragraph], but handle Emacs Lisp comments. "Like \\[fill-paragraph], but handle Emacs Lisp comments and docstrings.
If any of the current line is a comment, fill the comment or the If any of the current line is a comment, fill the comment or the
paragraph of it that point is in, preserving the comment's indentation paragraph of it that point is in, preserving the comment's indentation
and initial semicolons." and initial semicolons."
(interactive "P") (interactive "P")
(or (fill-comment-paragraph justify) (or (fill-comment-paragraph justify)
;; `paragraph-start' is set here (not in the buffer-local ;; Point is on a program line (a line no comment); we are interested
;; variable so that `forward-paragraph' et al work as ;; particularly in docstring lines.
;; expected) so that filling (doc) strings works sensibly. ;;
;; Adding the opening paren to avoid the following sexp being ;; We bind `paragraph-start' and `paragraph-separate' temporarily. They
;; filled means that sexps generally aren't filled as normal ;; are buffer-local, but we avoid changing them so that they can be set
;; text, which is probably sensible. The `;' and `:' stop the ;; to make `forward-paragraph' and friends do something the user wants.
;; filled para at following comment lines and keywords ;;
;; (typically in `defcustom'). ;; `paragraph-start': The `(' in the character alternative and the
;; left-singlequote plus `(' sequence after the \\| alternative prevent
;; sexps and backquoted sexps that follow a docstring from being filled
;; with the docstring. This setting has the consequence of inhibiting
;; filling many program lines that are not docstrings, which is sensible,
;; because the user probably asked to fill program lines by accident, or
;; expecting indentation (perhaps we should try to do indenting in that
;; case). The `;' and `:' stop the paragraph being filled at following
;; comment lines and at keywords (e.g., in `defcustom'). Left parens are
;; escaped to keep font-locking, filling, & paren matching in the source
;; file happy.
;;
;; `paragraph-separate': A clever regexp distinguishes the first line of
;; a docstring and identifies it as a paragraph separator, so that it
;; won't be filled. (Since the first line of documentation stands alone
;; in some contexts, filling should not alter the contents the author has
;; chosen.) Only the first line of a docstring begins with whitespace
;; and a quotation mark and ends with a period or (rarely) a comma.
;;
;; The `fill-column' is temporarily bound to
;; `emacs-lisp-docstring-fill-column' if that value is an integer.
(let ((paragraph-start (concat paragraph-start (let ((paragraph-start (concat paragraph-start
"\\|\\s-*[\(;:\"]")) "\\|\\s-*\\([\(;:\"]\\|`\(\\)"))
;; Avoid filling the first line of docstring.
(paragraph-separate (paragraph-separate
(concat paragraph-separate "\\|\\s-*\".*\\.$"))) (concat paragraph-separate "\\|\\s-*\".*[,\\.]$"))
(fill-column (if (integerp emacs-lisp-docstring-fill-column)
emacs-lisp-docstring-fill-column
fill-column)))
(fill-paragraph justify)) (fill-paragraph justify))
;; Never return nil. ;; Never return nil.
t)) t))