[Emacs-diffs] /srv/bzr/emacs/trunk r110372: Enhancements to docstring formatting when filling paragraphs.

[Fabián Ezequiel Gallina]

------------------------------------------------------------
revno: 110372
committer: Fabián Ezequiel Gallina <address@hidden>
branch nick: trunk
timestamp: Fri 2012-10-05 10:42:08 -0300
message:
  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.
modified:
  lisp/ChangeLog
  lisp/progmodes/python.el

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-10-05 07:38:05 +0000
+++ b/lisp/ChangeLog    2012-10-05 13:42:08 +0000
@@ -1,3 +1,11 @@
+2012-10-05  Fabián Ezequiel Gallina  <address@hidden>
+
+       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  <address@hidden>
 
        * net/newst-treeview.el (newsticker-group-move-feed): Doc fix.

=== modified file 'lisp/progmodes/python.el'
--- a/lisp/progmodes/python.el  2012-10-05 05:57:24 +0000
+++ b/lisp/progmodes/python.el  2012-10-05 13:42:08 +0000
@@ -2290,15 +2290,15 @@
   :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 @@
     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 @@
 
     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 @@
           ;; 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))