diff --git a/README.md b/README.md index 998c9f5..6fb951c 100644 --- a/README.md +++ b/README.md @@ -30,20 +30,20 @@ The text gets automatically *indented* and *split* on multiple lines. ### With [use-package](https://github.com/jwiegley/use-package) and [quelpa](https://github.com/quelpa/quelpa) ```elisp -(use-package insert-docstring +(use-package python-insert-docstring :ensure nil - :quelpa (insert-docstring + :quelpa (python-insert-docstring :fetcher github :repo "macurovc/insert-docstring")) ``` ### Manually -Place [insert-docstring.el](insert-docstring.el) in your Emacs `load-path`. E.g.: +Place [python-insert-docstring.el](python-insert-docstring.el) in your Emacs `load-path`. E.g.: ```elisp (add-to-list 'load-path (expand-file-name "~/{path/to}/insert-docstring")) -(require 'insert-docstring) +(require 'python-insert-docstring) ``` ## Usage @@ -52,7 +52,7 @@ Set in the `~/.emacs` file a keybinding such as: ```elisp (defun set-python-keybindings () - (local-set-key (kbd "C-c i") 'insert-docstring-at-point-with-google-style) + (local-set-key (kbd "C-c i") 'python-insert-docstring-with-google-style-at-point) ) (add-hook 'python-mode-hook 'set-python-keybindings) ``` @@ -63,12 +63,12 @@ the instructions. ## Contributing Any contribution is welcome. The file -[insert-docstring-tests.el](insert-docstring-tests.el) contains tests for the +[python-insert-docstring-tests.el](python-insert-docstring-tests.el) contains tests for the functions that don't require user inputs and don't modify a buffer. The tests can be run with the following command: ```bash -emacs -batch -l insert-docstring.el -l insert-docstring-tests.el -f ert-run-tests-batch-and-exit +emacs -batch -l python-insert-docstring.el -l python-insert-docstring-tests.el -f ert-run-tests-batch-and-exit ``` Each contribution must respect the following requirements: diff --git a/insert-docstring-tests.el b/python-insert-docstring-tests.el similarity index 65% rename from insert-docstring-tests.el rename to python-insert-docstring-tests.el index 4661e2c..35f3fab 100644 --- a/insert-docstring-tests.el +++ b/python-insert-docstring-tests.el @@ -1,4 +1,4 @@ -;;; insert-docstring-tests.el --- Tests for the Python Google docstring inserter -*- lexical-binding: t; -*- +;;; python-insert-docstring-tests.el --- Tests for the Python Google docstring inserter -*- lexical-binding: t; -*- ;; Copyright (c) 2021 Marco Vocialta @@ -24,120 +24,120 @@ ;;; Commentary: -;; This file contains tests for the functions in insert-docstring.el that don't -;; require user inputs and don't modify a buffer. +;; This file contains tests for the functions in python-insert-docstring.el that +;; don't require user inputs and don't modify a buffer. ;;; Code: -(defconst insert-docstring--fill-column 79) +(defconst python-insert-docstring--fill-column 79) (ert-deftest python-python-function-name-test () "Match the name of a simple function." (let ((string "def something()")) - (should (equal (string-match insert-docstring-python-function-name-regex string) 0)) + (should (equal (string-match python-insert-docstring-function-name-regex string) 0)) (should (equal (match-string 1 string) "something")))) (ert-deftest python-function-name-with-indent-test () "Match the name of a function with some indentation." (let ((string "\n \t def something (")) - (should (equal (string-match insert-docstring-python-function-name-regex string) 6)) + (should (equal (string-match python-insert-docstring-function-name-regex string) 6)) (should (equal (match-string 1 string) "something")))) (ert-deftest python-function-name-with-underscores-test () "Match the name of a function with underscores." (let ((string "\n \t def _something_else (")) - (should (equal (string-match insert-docstring-python-function-name-regex string) 6)) + (should (equal (string-match python-insert-docstring-function-name-regex string) 6)) (should (equal (match-string 1 string) "_something_else")))) (ert-deftest python-end-of-function-test () "Match the end of a function definition." - (should (equal (string-match insert-docstring-python-function-end-regex "):") 0)) - (should (equal (string-match insert-docstring-python-function-end-regex ") -> None : ") 0))) + (should (equal (string-match python-insert-docstring-function-end-regex "):") 0)) + (should (equal (string-match python-insert-docstring-function-end-regex ") -> None : ") 0))) (ert-deftest python-end-of-function-with-newline-test () "Match the end of a function definition with a None return type and newlines." (let ((string ") \n ->\n \n\nNone:\n")) - (should (equal (string-match insert-docstring-python-function-end-regex string) 0)))) + (should (equal (string-match python-insert-docstring-function-end-regex string) 0)))) (ert-deftest python-end-of-function-with-type-test () "Match the end of a function definition with an elaborate return type." (let ((string " ) \n ->\n \n\nMap[int, int]:\n")) - (should (equal (string-match insert-docstring-python-function-end-regex string) 2)))) + (should (equal (string-match python-insert-docstring-function-end-regex string) 2)))) (ert-deftest python-argument-string-regex-test () "Match the arguments string." (let ((string "def toto_blabla(hey1):")) - (should (equal (string-match insert-docstring-python-function-arguments-regex string) 15)) + (should (equal (string-match python-insert-docstring-function-arguments-regex string) 15)) (should (equal (match-string 1 string) "hey1")))) (ert-deftest python-argument-string-regex-test () "Match the arguments string." (let ((string "\ndef\n\ntoto( bubu : List[str] , lala ) -> \n\nNone : ")) - (should (equal (string-match insert-docstring-python-function-arguments-regex string) 10)) + (should (equal (string-match python-insert-docstring-function-arguments-regex string) 10)) (should (equal (match-string 1 string) " bubu : List[str] , lala ")))) (ert-deftest python-argument-string-regex-with-newlines-test () "Match the arguments string." (let ((string "\ndef\n\ntoto( bubu : List[str] ,\n lala ) -> \n\nNone : ")) - (should (equal (string-match insert-docstring-python-function-arguments-regex string) 10)) + (should (equal (string-match python-insert-docstring-function-arguments-regex string) 10)) (should (equal (match-string 1 string) " bubu : List[str] ,\n lala ")))) (ert-deftest python-function-indentation-test () "Match the arguments string." (let ((string "\ndef\n\ntoto() -> \n\nNone : ")) - (should (equal (string-match insert-docstring-python-function-indentation-regex string) 1)) + (should (equal (string-match python-insert-docstring-function-indentation-regex string) 1)) (should (equal (match-string 1 string) "")))) (ert-deftest python-function-indentation-with-tabs-and-spaces-test () "Match the arguments string." (let ((string "\n \t def\n\ntoto() -> \n\nNone : ")) - (should (equal (string-match insert-docstring-python-function-indentation-regex string) 1)) + (should (equal (string-match python-insert-docstring-function-indentation-regex string) 1)) (should (equal (match-string 1 string) " \t ")))) (ert-deftest python-parse-argument-list-test () "Test the arguments list parser function." (progn - (should (equal (insert-docstring--get-python-arguments-names-from-string "") nil)) - (should (equal (insert-docstring--get-python-arguments-names-from-string + (should (equal (python-insert-docstring--get-arguments-names-from-string "") nil)) + (should (equal (python-insert-docstring--get-arguments-names-from-string "one") '("one"))) - (should (equal (insert-docstring--get-python-arguments-names-from-string + (should (equal (python-insert-docstring--get-arguments-names-from-string " first, second, third ") '("first" "second" "third"))) - (should (equal (insert-docstring--get-python-arguments-names-from-string + (should (equal (python-insert-docstring--get-arguments-names-from-string " first: Type, second: Map[some, other], third : Dict[str, List[str]] ") '("first" "second" "third"))) - (should (equal (insert-docstring--get-python-arguments-names-from-string + (should (equal (python-insert-docstring--get-arguments-names-from-string " first: Type\n,\n second:\n Map[some, other]") '("first" "second"))) - (should (equal (insert-docstring--get-python-arguments-names-from-string + (should (equal (python-insert-docstring--get-arguments-names-from-string " first: Type = 1,\n second: Map[some, other] = 2") '("first" "second"))) - (should (equal (insert-docstring--get-python-arguments-names-from-string + (should (equal (python-insert-docstring--get-arguments-names-from-string " first = 1,\n second = 2") '("first" "second"))))) (ert-deftest prefix-lines-test () "Test the function to prefix lines with blanks." - (should (equal (insert-docstring--prefix-lines '("some" "lines") " ") '(" some" " lines"))) - (should (equal (insert-docstring--prefix-lines '("some" "") " ") '(" some" "")))) + (should (equal (python-insert-docstring--prefix-lines '("some" "lines") " ") '(" some" " lines"))) + (should (equal (python-insert-docstring--prefix-lines '("some" "") " ") '(" some" "")))) (ert-deftest python-google-docstring-arguments-test () "Test the generation of the argument list in the docstring." - (should (equal (insert-docstring--python-google-docstring-arguments () "") nil)) - (let ((arguments (list (make-insert-docstring--argument-data :name "one" :description "this one") - (make-insert-docstring--argument-data :name "two" :description "this two")))) - (should (equal (insert-docstring--python-google-docstring-arguments arguments "pre") + (should (equal (python-insert-docstring--google-docstring-arguments () "") nil)) + (let ((arguments (list (make-python-insert-docstring--argument-data :name "one" :description "this one") + (make-python-insert-docstring--argument-data :name "two" :description "this two")))) + (should (equal (python-insert-docstring--google-docstring-arguments arguments "pre") '("" "preArgs:" "pre one: this one" "pre two: this two"))))) (ert-deftest python-google-docstring-returns-test () "Test the generation of the return statement in the docstring." - (should (equal (insert-docstring--python-google-docstring-returns nil "") nil)) - (should (equal (insert-docstring--python-google-docstring-returns "something" "") + (should (equal (python-insert-docstring--google-docstring-returns nil "") nil)) + (should (equal (python-insert-docstring--google-docstring-returns "something" "") '("" "Returns:" " something"))) - (should (equal (insert-docstring--python-google-docstring-returns "something" " ") + (should (equal (python-insert-docstring--google-docstring-returns "something" " ") '("" " Returns:" " something")))) (ert-deftest python-google-docstring-title-only () "Test the generation of the entire docstring." (should (equal - (insert-docstring--python-google-docstring - (make-insert-docstring--function-data + (python-insert-docstring--google-docstring + (make-python-insert-docstring--function-data :indentation-string "" :short-description "title" :long-description nil @@ -150,8 +150,8 @@ (ert-deftest python-google-docstring-title-and-return () "Test the generation of the entire docstring." (should (equal - (insert-docstring--python-google-docstring - (make-insert-docstring--function-data + (python-insert-docstring--google-docstring + (make-python-insert-docstring--function-data :indentation-string "" :short-description "title" :long-description nil @@ -167,13 +167,13 @@ (ert-deftest python-google-docstring-title-args-and-return () "Test the generation of the entire docstring." (should (equal - (insert-docstring--python-google-docstring - (make-insert-docstring--function-data + (python-insert-docstring--google-docstring + (make-python-insert-docstring--function-data :indentation-string "" :short-description "title" :long-description nil - :arguments (list (make-insert-docstring--argument-data :name "one" :description "this one") - (make-insert-docstring--argument-data :name "two" :description "this two")) + :arguments (list (make-python-insert-docstring--argument-data :name "one" :description "this one") + (make-python-insert-docstring--argument-data :name "two" :description "this two")) :return "something")) '(" \"\"\"title" "" @@ -189,13 +189,13 @@ (ert-deftest python-google-docstring-title-and-args () "Test the generation of the entire docstring." (should (equal - (insert-docstring--python-google-docstring - (make-insert-docstring--function-data + (python-insert-docstring--google-docstring + (make-python-insert-docstring--function-data :indentation-string "" :short-description "title" :long-description nil - :arguments (list (make-insert-docstring--argument-data :name "one" :description "this one") - (make-insert-docstring--argument-data :name "two" :description "this two")) + :arguments (list (make-python-insert-docstring--argument-data :name "one" :description "this one") + (make-python-insert-docstring--argument-data :name "two" :description "this two")) :return nil)) '(" \"\"\"title" "" @@ -208,15 +208,15 @@ (ert-deftest python-google-docstring-all-fields () "Test the generation of the entire docstring." (should (equal - (insert-docstring--python-google-docstring - (make-insert-docstring--function-data + (python-insert-docstring--google-docstring + (make-python-insert-docstring--function-data :indentation-string " " :short-description "this is a very very very very very very very very very very very very long title" :long-description "this is a very very very very very very very very very very very very long description" - :arguments (list (make-insert-docstring--argument-data + :arguments (list (make-python-insert-docstring--argument-data :name "one" :description "this one is very very very very very very very very very very long") - (make-insert-docstring--argument-data :name "two" :description "this two")) + (make-python-insert-docstring--argument-data :name "two" :description "this two")) :return "what a very very very very very very very very very very very very long return")) '(" \"\"\"this is a very very very very very very very very very very very" " very long title" @@ -238,34 +238,34 @@ (ert-deftest indentation-length () "Test the computation of the indentation length." - (should (equal (insert-docstring--indentation-length "") 0)) - (should (equal (insert-docstring--indentation-length " ") 1)) - (should (equal (insert-docstring--indentation-length " ") 3)) - (should (equal (insert-docstring--indentation-length " \t " 2) 5)) - (should (equal (insert-docstring--indentation-length " \t \t " 3) 11))) + (should (equal (python-insert-docstring--indentation-length "") 0)) + (should (equal (python-insert-docstring--indentation-length " ") 1)) + (should (equal (python-insert-docstring--indentation-length " ") 3)) + (should (equal (python-insert-docstring--indentation-length " \t " 2) 5)) + (should (equal (python-insert-docstring--indentation-length " \t \t " 3) 11))) (ert-deftest append-words-to-paragraph () "Test the function to append words to a paragraph." - (should (equal (insert-docstring--append-words-to-paragraph () 5 '("one" "two" "three")) + (should (equal (python-insert-docstring--append-words-to-paragraph () 5 '("one" "two" "three")) '("one" "two" "three"))) - (should (equal (insert-docstring--append-words-to-paragraph () 7 '("one" "two" "three")) + (should (equal (python-insert-docstring--append-words-to-paragraph () 7 '("one" "two" "three")) '("one two" "three"))) - (should (equal (insert-docstring--append-words-to-paragraph () 13 '("one" "two" "three")) + (should (equal (python-insert-docstring--append-words-to-paragraph () 13 '("one" "two" "three")) '("one two three"))) - (should (equal (insert-docstring--append-words-to-paragraph '("one") 7 '("two" "three")) + (should (equal (python-insert-docstring--append-words-to-paragraph '("one") 7 '("two" "three")) '("one two" "three"))) - (should (equal (insert-docstring--append-words-to-paragraph '("one") 7 '("two" "three") " ") + (should (equal (python-insert-docstring--append-words-to-paragraph '("one") 7 '("two" "three") " ") '("one two" " three"))) - (should (equal (insert-docstring--append-words-to-paragraph () 7 '("two" "three") " ") + (should (equal (python-insert-docstring--append-words-to-paragraph () 7 '("two" "three") " ") '("two" " three")))) (ert-deftest line-to-indented-paragraph () "Test splitting a line into a paragraph." - (should (equal (insert-docstring--line-to-indented-paragraph "this is a line" " " " " 9) + (should (equal (python-insert-docstring--line-to-indented-paragraph "this is a line" " " " " 9) '(" this is" " a line")))) ;; End: -;;; insert-docstring-tests.el ends here +;;; python-insert-docstring-tests.el ends here diff --git a/insert-docstring.el b/python-insert-docstring.el similarity index 51% rename from insert-docstring.el rename to python-insert-docstring.el index 35c9f8d..e5ab1d6 100644 --- a/insert-docstring.el +++ b/python-insert-docstring.el @@ -1,4 +1,4 @@ -;;; insert-docstring.el --- Python Google docstring inserter -*- lexical-binding: t; -*- +;;; python-insert-docstring.el --- Python Google docstring inserter -*- lexical-binding: t; -*- ;; Copyright (c) 2021 Marco Vocialta @@ -35,7 +35,7 @@ ;; ~/.emacs file such as: ;; (defun set-python-keybindings () -;; (local-set-key (kbd "C-c i") 'insert-docstring-at-point-with-google-style) +;; (local-set-key (kbd "C-c i") 'python-insert-docstring-with-google-style-at-point) ;; ) ;; (add-hook 'python-mode-hook 'set-python-keybindings) @@ -46,110 +46,110 @@ (require 'cl-lib) -(defgroup insert-docstring nil "Insert Docstring custom variables" +(defgroup python-insert-docstring nil "Insert Docstring custom variables" :group 'convenience) -(defcustom insert-docstring-python-tab-width (if (boundp 'python-tab-width) +(defcustom python-insert-docstring-tab-width (if (boundp 'python-tab-width) python-tab-width 4) "Tabulation width in Python files." - :group 'insert-docstring + :group 'python-insert-docstring :type 'integer) -(defcustom insert-docstring-default-python-indentation (make-string insert-docstring-python-tab-width +(defcustom python-insert-docstring-default-indentation (make-string python-insert-docstring-tab-width ?\s) "Python indentation string." - :group 'insert-docstring + :group 'python-insert-docstring :type 'string) -(defcustom insert-docstring-python-function-indentation-regex (rx line-start +(defcustom python-insert-docstring-function-indentation-regex (rx line-start (group (* blank)) "def" (or blank "\n")) "Regex to find the indentation of a function." - :group 'insert-docstring + :group 'python-insert-docstring :type 'string) -(defcustom insert-docstring-python-function-name-regex (rx "def" +(defcustom python-insert-docstring-function-name-regex (rx "def" (+ (or blank "\n")) (group (+ (not whitespace))) (* (or blank "\n")) "(") "Regex to find the name of a function." - :group 'insert-docstring + :group 'python-insert-docstring :type 'string) -(defcustom insert-docstring-python-function-arguments-regex (rx "(" +(defcustom python-insert-docstring-function-arguments-regex (rx "(" (group (* (not (any "(" ")")))) ")") "Regex to find the string of arguments of a function." - :group 'insert-docstring + :group 'python-insert-docstring :type 'string) -(defcustom insert-docstring-python-function-end-regex (rx ")" +(defcustom python-insert-docstring-function-end-regex (rx ")" (* (not (any ":"))) ":") "Regex to find the end of a function." - :group 'insert-docstring + :group 'python-insert-docstring :type 'string) -(defcustom insert-docstring-blank-or-newline-regex (rx (+ (or blank "\n"))) +(defcustom python-insert-docstring-blank-or-newline-regex (rx (+ (or blank "\n"))) "Regex to find blanks and newlines (used for trimming)." - :group 'insert-docstring + :group 'python-insert-docstring :type 'string) -(cl-defstruct insert-docstring--argument-data +(cl-defstruct python-insert-docstring--argument-data "Data associated to a function argument." name description) -(cl-defstruct insert-docstring--function-data +(cl-defstruct python-insert-docstring--function-data "Data associated to a function." indentation-string short-description long-description arguments return) ;;;###autoload -(defun insert-docstring-at-point-with-google-style () +(defun python-insert-docstring-with-google-style-at-point () "Insert a Google docstring for the Python function at point." (interactive) - (let* ((function-data (insert-docstring--function-data-at-point)) - (google-docstring (insert-docstring--python-google-docstring + (let* ((function-data (python-insert-docstring--function-data-at-point)) + (google-docstring (python-insert-docstring--google-docstring function-data))) - (insert-docstring--insert-python-docstring-with-indentation + (python-insert-docstring--insert-docstring-with-indentation google-docstring))) -(defun insert-docstring--function-data-at-point () +(defun python-insert-docstring--function-data-at-point () "Return a function-data struct with the data of the function at point." - (let ((indentation-string (insert-docstring--match-string-for-python-function-at-point - insert-docstring-python-function-indentation-regex)) - (function-name (insert-docstring--match-string-for-python-function-at-point - insert-docstring-python-function-name-regex)) - (arguments-string (insert-docstring--match-string-for-python-function-at-point - insert-docstring-python-function-arguments-regex))) - (insert-docstring--make-function-data indentation-string - function-name - (insert-docstring--get-python-arguments-names-from-string - arguments-string)))) - - -(defun insert-docstring--match-string-for-python-function-at-point (regex) + (let ((indentation-string (python-insert-docstring--match-string-for-function-at-point + python-insert-docstring-function-indentation-regex)) + (function-name (python-insert-docstring--match-string-for-function-at-point + python-insert-docstring-function-name-regex)) + (arguments-string (python-insert-docstring--match-string-for-function-at-point + python-insert-docstring-function-arguments-regex))) + (python-insert-docstring--make-function-data indentation-string + function-name + (python-insert-docstring--get-arguments-names-from-string + arguments-string)))) + + +(defun python-insert-docstring--match-string-for-function-at-point (regex) "Match REGEX for the python function at point and return its first group." (save-excursion (end-of-line) - (re-search-backward insert-docstring-python-function-indentation-regex) + (re-search-backward python-insert-docstring-function-indentation-regex) (re-search-forward regex) (match-string 1))) -(defun insert-docstring--get-python-arguments-names-from-string (arguments-string) +(defun python-insert-docstring--get-arguments-names-from-string (arguments-string) "Parse the argument names contained in ARGUMENTS-STRING and return them in a list." (if (string-equal "" arguments-string) nil (mapcar (lambda (string) "Remove default value if any and trim" - (car (split-string string "=" t insert-docstring-blank-or-newline-regex))) + (car (split-string string "=" t python-insert-docstring-blank-or-newline-regex))) (cl-remove-if (lambda (string) "Match type data leftovers" (string-match-p (rx (or "[" "]")) @@ -160,42 +160,43 @@ (split-string arguments-string ",")))))) -(defun insert-docstring--make-function-data (indentation-string function-name argument-names) +(defun python-insert-docstring--make-function-data (indentation-string function-name argument-names) "Create a function-data struct. Argument INDENTATION-STRING indentation of the function. Argument FUNCTION-NAME name of the function. Argument ARGUMENT-NAMES names of the function arguments." - (make-insert-docstring--function-data :indentation-string indentation-string - :short-description (insert-docstring--get-short-description-from-user - function-name):long-description - (insert-docstring--get-long-description-from-user - function-name) - :arguments (insert-docstring--make-arguments-data argument-names):return - (insert-docstring--get-return-description-from-user))) + (make-python-insert-docstring--function-data :indentation-string indentation-string + :short-description (python-insert-docstring--get-short-description-from-user + function-name):long-description + (python-insert-docstring--get-long-description-from-user + function-name) + :arguments (python-insert-docstring--make-arguments-data + argument-names):return + (python-insert-docstring--get-return-description-from-user))) -(defun insert-docstring--make-argument-data (argument-name) +(defun python-insert-docstring--make-argument-data (argument-name) "Generate an arguments-data struct. The user is asked to input the argument description. Argument ARGUMENT-NAME name of the argument." - (make-insert-docstring--argument-data :name argument-name - :description (read-string (format "Enter the description for argument '%s': " - argument-name)))) + (make-python-insert-docstring--argument-data :name argument-name + :description (read-string (format "Enter the description for argument '%s': " + argument-name)))) -(defun insert-docstring--make-arguments-data (argument-names) +(defun python-insert-docstring--make-arguments-data (argument-names) "Generate an arguments-data struct for each argument in ARGUMENT-NAMES. The user is asked for the description of each argument." - (mapcar #'insert-docstring--make-argument-data + (mapcar #'python-insert-docstring--make-argument-data argument-names)) -(defun insert-docstring--get-short-description-from-user (function-name) +(defun python-insert-docstring--get-short-description-from-user (function-name) "Ask the user for the short description of the function with name FUNCTION-NAME." (read-string (format "Enter the short description for the function '%s': " function-name))) -(defun insert-docstring--get-long-description-from-user (function-name) +(defun python-insert-docstring--get-long-description-from-user (function-name) "Ask the user for the long description of the function with name FUNCTION-NAME." (let ((description (read-string (format "Enter the long description for the function '%s' (leave empty to omit it): " function-name)))) @@ -204,7 +205,7 @@ The user is asked for the description of each argument." description))) -(defun insert-docstring--get-return-description-from-user () +(defun python-insert-docstring--get-return-description-from-user () "Ask the user of the description of the returned data." (let ((description (read-string "Enter the return description (leave empty to omit it): "))) (if (string-equal description "") @@ -212,7 +213,7 @@ The user is asked for the description of each argument." description))) -(defun insert-docstring--prefix-lines (lines prefix) +(defun python-insert-docstring--prefix-lines (lines prefix) "Prepend each string in the LINES list with the PREFIX string. The result is a list of strings. If a string is empty, PREFIX doesn't get prepended." @@ -223,117 +224,120 @@ If a string is empty, PREFIX doesn't get prepended." lines)) -(defun insert-docstring--insert-python-docstring-with-indentation (docstring-lines) +(defun python-insert-docstring--insert-docstring-with-indentation (docstring-lines) "Insert the DOCSTRING-LINES in the buffer." (save-excursion (end-of-line) - (re-search-backward insert-docstring-python-function-indentation-regex) - (re-search-forward insert-docstring-python-function-end-regex) + (re-search-backward python-insert-docstring-function-indentation-regex) + (re-search-forward python-insert-docstring-function-end-regex) (insert "\n") (insert (mapconcat #'identity docstring-lines "\n")))) -(defun insert-docstring--python-google-docstring (function-data) +(defun python-insert-docstring--google-docstring (function-data) "Return the Google docstring lines corresponding to FUNCTION-DATA." - (let ((docstring-indentation (concat (insert-docstring--function-data-indentation-string + (let ((docstring-indentation (concat (python-insert-docstring--function-data-indentation-string function-data) - insert-docstring-default-python-indentation)) - (short-description (insert-docstring--function-data-short-description + python-insert-docstring-default-indentation)) + (short-description (python-insert-docstring--function-data-short-description function-data)) - (long-description (insert-docstring--function-data-long-description + (long-description (python-insert-docstring--function-data-long-description function-data)) - (arguments (insert-docstring--function-data-arguments + (arguments (python-insert-docstring--function-data-arguments function-data)) - (return (insert-docstring--function-data-return function-data))) - (nconc (insert-docstring--line-to-indented-paragraph (format "\"\"\"%s" short-description) - docstring-indentation) - (insert-docstring--python-google-docstring-long-description + (return (python-insert-docstring--function-data-return + function-data))) + (nconc (python-insert-docstring--line-to-indented-paragraph (format "\"\"\"%s" short-description) + docstring-indentation) + (python-insert-docstring--google-docstring-long-description long-description docstring-indentation) - (insert-docstring--python-google-docstring-arguments + (python-insert-docstring--google-docstring-arguments arguments docstring-indentation) - (insert-docstring--python-google-docstring-returns + (python-insert-docstring--google-docstring-returns return docstring-indentation) - (insert-docstring--prefix-lines '("" "\"\"\"") - docstring-indentation)))) + (python-insert-docstring--prefix-lines '("" "\"\"\"") + docstring-indentation)))) -(defun insert-docstring--python-google-docstring-long-description (long-description docstring-indentation) +(defun python-insert-docstring--google-docstring-long-description (long-description docstring-indentation) "Return the LONG-DESCRIPTION with the given DOCSTRING-INDENTATION." (if long-description (nconc (list "") - (insert-docstring--line-to-indented-paragraph + (python-insert-docstring--line-to-indented-paragraph long-description docstring-indentation)))) -(defun insert-docstring--python-google-docstring-arguments (arguments docstring-indentation) +(defun python-insert-docstring--google-docstring-arguments (arguments docstring-indentation) "Return the docstring lines about the ARGUMENTS with the given DOCSTRING-INDENTATION." - (let ((argument-indentation (concat docstring-indentation insert-docstring-default-python-indentation))) + (let ((argument-indentation (concat docstring-indentation python-insert-docstring-default-indentation))) (nconc (if arguments (nconc (list "") - (insert-docstring--prefix-lines '("Args:") - docstring-indentation))) - (insert-docstring--python-google-docstring-arguments-list + (python-insert-docstring--prefix-lines '("Args:") + docstring-indentation))) + (python-insert-docstring--google-docstring-arguments-list arguments argument-indentation)))) -(defun insert-docstring--python-google-docstring-argument-description (argument-data arguments-docstring-indentation) +(defun python-insert-docstring--google-docstring-argument-description (argument-data arguments-docstring-indentation) "Generate a docstring paragraph with the description of an argument. Argument ARGUMENT-DATA struct with the argument data. Argument ARGUMENTS-DOCSTRING-INDENTATION intentation of the argument paragraph." - (let ((name (insert-docstring--argument-data-name argument-data)) - (description (insert-docstring--argument-data-description + (let ((name (python-insert-docstring--argument-data-name + argument-data)) + (description (python-insert-docstring--argument-data-description argument-data))) - (insert-docstring--line-to-indented-paragraph (format "%s: %s" name description) - arguments-docstring-indentation - insert-docstring-default-python-indentation))) + (python-insert-docstring--line-to-indented-paragraph (format "%s: %s" name description) + arguments-docstring-indentation + python-insert-docstring-default-indentation))) -(defun insert-docstring--python-google-docstring-arguments-list (arguments arguments-docstring-indentation) +(defun python-insert-docstring--google-docstring-arguments-list (arguments arguments-docstring-indentation) "Return the docstring lines about the ARGUMENTS list with the given ARGUMENTS-DOCSTRING-INDENTATION." (cl-reduce #'nconc (mapcar (lambda (argument) - (insert-docstring--python-google-docstring-argument-description + (python-insert-docstring--google-docstring-argument-description argument arguments-docstring-indentation)) arguments))) -(defun insert-docstring--python-google-docstring-returns (return-description docstring-indentation) +(defun python-insert-docstring--google-docstring-returns (return-description docstring-indentation) "Return the RETURN-DESCRIPTION with the given DOCSTRING-INDENTATION." (if return-description (nconc (list "") - (insert-docstring--prefix-lines '("Returns:") - docstring-indentation) - (insert-docstring--line-to-indented-paragraph return-description - (concat insert-docstring-default-python-indentation - docstring-indentation))))) + (python-insert-docstring--prefix-lines '("Returns:") + docstring-indentation) + (python-insert-docstring--line-to-indented-paragraph return-description + (concat python-insert-docstring-default-indentation + docstring-indentation))))) -(defun insert-docstring--line-to-indented-paragraph (line indentation &optional new-line-prefix - column-width) +(defun python-insert-docstring--line-to-indented-paragraph (line indentation &optional new-line-prefix + column-width) "Split a LINE into multiple ones to form a paragraph column. Argument INDENTATION indentation prefixed to each paragraph row. Optional argument NEW-LINE-PREFIX prefix string for new lines. Optional argument COLUMN-WIDTH maximum lenght of a line." (let ((max-length (- (or column-width - (insert-docstring--get-fill-column)) - (insert-docstring--indentation-length indentation)))) - (insert-docstring--prefix-lines (insert-docstring--append-words-to-paragraph () - max-length - (split-string line) - new-line-prefix) - indentation))) + (python-insert-docstring--get-fill-column)) + (python-insert-docstring--indentation-length + indentation)))) + (python-insert-docstring--prefix-lines (python-insert-docstring--append-words-to-paragraph () + max-length + (split-string line) + new-line-prefix) + indentation))) -(defun insert-docstring--get-fill-column () +(defun python-insert-docstring--get-fill-column () "Return the fill column value." - (if (boundp 'insert-docstring--fill-column) - insert-docstring--fill-column + (if (boundp 'python-insert-docstring--fill-column) + python-insert-docstring--fill-column (if (boundp 'python-fill-column) python-fill-column fill-column))) -(defun insert-docstring--indentation-length (indentation-string &optional num-tab-chars) +(defun python-insert-docstring--indentation-length (indentation-string &optional num-tab-chars) "Compute the number of character in INDENTATION-STRING. Tabs count according to their width. Optional argument NUM-TAB-CHARS number of spaces in a tabulation (default: `tab-width')." @@ -345,29 +349,29 @@ Optional argument NUM-TAB-CHARS number of spaces in a tabulation (default: `tab- indentation-string))) -(defun insert-docstring--append-words-to-paragraph (lines max-line-width words &optional new-line-prefix) +(defun python-insert-docstring--append-words-to-paragraph (lines max-line-width words &optional new-line-prefix) "Append the WORDS to the strings in LINES. A new line is appended whenever MAX-LINE-WIDTH is reached. New lines can be optionally prefixed with NEW-LINE-PREFIX." (if words - (insert-docstring--append-words-to-paragraph (let ((next-word (car words)) - (next-line (car (last lines)))) - (if next-line - (if (<= (+ (length next-line) - (length next-word) - 1) max-line-width) - (nconc (nbutlast lines) - (list (concat next-line " " next-word))) - (nconc lines - (list (concat new-line-prefix next-word)))) - (list next-word))) - max-line-width - (cdr words) - new-line-prefix) + (python-insert-docstring--append-words-to-paragraph (let ((next-word (car words)) + (next-line (car (last lines)))) + (if next-line + (if (<= (+ (length next-line) + (length next-word) + 1) max-line-width) + (nconc (nbutlast lines) + (list (concat next-line " " next-word))) + (nconc lines + (list (concat new-line-prefix next-word)))) + (list next-word))) + max-line-width + (cdr words) + new-line-prefix) lines)) ;; End: -(provide 'insert-docstring) +(provide 'python-insert-docstring) -;;; insert-docstring.el ends here +;;; python-insert-docstring.el ends here