procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Enhancements to docstring formatting when filling paragraphs.

Browse source 
* 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.
This commit is contained in:
Fabián Ezequiel Gallina 2012-10-05 10:42:08 -03:00
parent a65fbb5f0e
commit 7fa36ccb71
2 changed files with 40 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
lisp/ChangeLog
View file

@ -1,3 +1,11 @@
2012-10-05 Fabián Ezequiel Gallina <fgallina@cuca>
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 <rgm@gnu.org>
* net/newst-treeview.el (newsticker-group-move-feed): Doc fix.

46
lisp/progmodes/python.el
View file

@ -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))