From 7fa36ccb71d0def28bc3f8eb17827fc870bd7ca2 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Fabi=C3=A1n=20Ezequiel=20Gallina?= Date: Fri, 5 Oct 2012 10:42:08 -0300 Subject: [PATCH] Enhancements to docstring formatting when filling paragraphs. * progmodes/python.el (python-fill-docstring-style): Rename from python-fill-string-style. Added new style. (python-fill-string): Use new style. Better checks for docstrings. --- lisp/ChangeLog | 8 +++++++ lisp/progmodes/python.el | 46 ++++++++++++++++++++++++++++------------ 2 files changed, 40 insertions(+), 14 deletions(-) diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 16c64ae1394..1010fc0ae11 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,11 @@ +2012-10-05 Fabián Ezequiel Gallina + + Enhancements to docstring formatting when filling paragraphs. + * progmodes/python.el (python-fill-docstring-style): Rename from + python-fill-string-style. Added new style. + (python-fill-string): Use new style. Better checks for + docstrings. + 2012-10-05 Glenn Morris * net/newst-treeview.el (newsticker-group-move-feed): Doc fix. diff --git a/lisp/progmodes/python.el b/lisp/progmodes/python.el index d5aa73f5ef3..b3b3b0181d7 100644 --- a/lisp/progmodes/python.el +++ b/lisp/progmodes/python.el @@ -2290,15 +2290,15 @@ fill parens." :type 'symbol :group 'python) -(defcustom python-fill-string-style 'pep-257 +(defcustom python-fill-docstring-style 'pep-257 "Style used to fill docstrings. This affects `python-fill-string' behavior with regards to triple quotes positioning. -Possible values are DJANGO, PEP-257, PEP-257-NN, SYMMETRIC and -NIL. A value of NIL won't care about quotes position, will do -what `fill-paragraph' does, any other value may result in one of -the following docstring styles: +Possible values are DJANGO, ONETWO, PEP-257, PEP-257-NN, +SYMMETRIC, and NIL. A value of NIL won't care about quotes +position and will treat docstrings a normal string, any other +value may result in one of the following docstring styles: DJANGO: @@ -2312,6 +2312,17 @@ DJANGO: If processing fails throw ProcessingError. \"\"\" +ONETWO: + + \"\"\"Process foo, return bar.\"\"\" + + \"\"\" + Process foo, return bar. + + If processing fails throw ProcessingError. + + \"\"\" + PEP-257: \"\"\"Process foo, return bar.\"\"\" @@ -2340,9 +2351,16 @@ SYMMETRIC: If processing fails throw ProcessingError. \"\"\"" - :type 'symbol + :type '(choice + (const :tag "Don't format docstrings" nil) + (const :tag "Django's coding standards style." django) + (const :tag "One newline and start and Two at end style." onetwo) + (const :tag "PEP-257 with 2 newlines at end of string." pep-257) + (const :tag "PEP-257 with 1 newline at end of string." pep-257-nn) + (const :tag "Symmetric style." symmetric)) :group 'python - :safe (lambda (val) (memq val '(django pep-257 pep-257-nn symmetric nil)))) + :safe (lambda (val) + (memq val '(django onetwo pep-257 pep-257-nn symmetric nil)))) (defun python-fill-paragraph-function (&optional justify) "`fill-paragraph-function' handling multi-line strings and possibly comments. @@ -2403,28 +2421,28 @@ JUSTIFY should be used (if applicable) as in `fill-paragraph'." ;; Docstring styles may vary for oneliners and multi-liners. (> (count-matches "\n" str-start-pos str-end-pos) 0)) (delimiters-style - (case python-fill-string-style + (case python-fill-docstring-style ;; delimiters-style is a cons cell with the form ;; (START-NEWLINES . END-NEWLINES). When any of the sexps ;; is NIL means to not add any newlines for start or end - ;; of docstring. See `python-fill-string-style' for a + ;; of docstring. See `python-fill-docstring-style' for a ;; graphic idea of each style. + (django (cons 1 1)) + (onetwo (and multi-line-p (cons 1 2))) (pep-257 (and multi-line-p (cons nil 2))) (pep-257-nn (and multi-line-p (cons nil 1))) - (django (cons 1 1)) (symmetric (and multi-line-p (cons 1 1))))) (docstring-p (save-excursion ;; Consider docstrings those strings which ;; start on a line by themselves. - (goto-char str-start-pos) - (skip-chars-backward (rx whitespace)) - (= (point) (line-beginning-position)))) + (python-nav-beginning-of-statement) + (and (= (point) str-start-pos)))) (fill-paragraph-function)) (save-restriction (narrow-to-region str-start-pos str-end-pos) (fill-paragraph justify)) (save-excursion - (when (and docstring-p python-fill-string-style) + (when (and docstring-p python-fill-docstring-style) ;; Add the number of newlines indicated by the selected style ;; at the start of the docstring. (goto-char (+ str-start-pos num-quotes)) -- 2.39.2