From fd16b061a9e6e89c905a7d7813867090622969e9 Mon Sep 17 00:00:00 2001 From: Juanma Barranquero Date: Sat, 15 Mar 2014 18:37:58 +0100 Subject: [PATCH] lisp/progmodes/python.el: Fix docstring typos. (defconst, python-syntax-count-quotes) (python-indent-region, python-indent-shift-right) (python-indent-dedent-line-backspace, python-nav-backward-sexp) (python-nav-backward-sexp-safe, python-nav-backward-up-list) (python-shell-prompt-block-regexp, python-shell-prompt-output-regexp) (python-shell-prompt-pdb-regexp, python-shell-enable-font-lock) (inferior-python-mode, python-shell-make-comint, run-python-internal) (python-shell-buffer-substring, python-shell-send-buffer) (python-pdbtrack-activate, python-pdbtrack-stacktrace-info-regexp) (python-completion-complete-at-point, python-fill-docstring-style) (python-eldoc-function, python-imenu-format-item-label) (python-imenu-format-parent-item-label) (python-imenu-format-parent-item-jump-label) (python-imenu--build-tree, python-imenu-create-index) (python-imenu-create-flat-index): Fix docstring typos. (python-indent-context, python-shell-prompt-regexp, run-python): Remove superfluous backslashes. (python-indent-line, python-nav-beginning-of-defun) (python-shell-get-buffer, python-shell-get-process) (python-info-current-defun, python-info-current-line-comment-p) (python-info-current-line-empty-p, python-util-popn): Doc fixes. (python-indent-post-self-insert-function, python-shell-send-file) (python-shell-completion-get-completions) (python-shell-completion-complete-or-indent) (python-eldoc--get-doc-at-point): Reflow docstrings. --- lisp/ChangeLog | 30 ++++++- lisp/progmodes/python.el | 165 +++++++++++++++++++-------------------- 2 files changed, 110 insertions(+), 85 deletions(-) diff --git a/lisp/ChangeLog b/lisp/ChangeLog index fccf82e2557..33d203e121f 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,31 @@ +2014-03-15 Juanma Barranquero + + * progmodes/python.el (defconst, python-syntax-count-quotes) + (python-indent-region, python-indent-shift-right) + (python-indent-dedent-line-backspace, python-nav-backward-sexp) + (python-nav-backward-sexp-safe, python-nav-backward-up-list) + (python-shell-prompt-block-regexp, python-shell-prompt-output-regexp) + (python-shell-prompt-pdb-regexp, python-shell-enable-font-lock) + (inferior-python-mode, python-shell-make-comint, run-python-internal) + (python-shell-buffer-substring, python-shell-send-buffer) + (python-pdbtrack-activate, python-pdbtrack-stacktrace-info-regexp) + (python-completion-complete-at-point, python-fill-docstring-style) + (python-eldoc-function, python-imenu-format-item-label) + (python-imenu-format-parent-item-label) + (python-imenu-format-parent-item-jump-label) + (python-imenu--build-tree, python-imenu-create-index) + (python-imenu-create-flat-index): Fix docstring typos. + (python-indent-context, python-shell-prompt-regexp, run-python): + Remove superfluous backslashes. + (python-indent-line, python-nav-beginning-of-defun) + (python-shell-get-buffer, python-shell-get-process) + (python-info-current-defun, python-info-current-line-comment-p) + (python-info-current-line-empty-p, python-util-popn): Doc fixes. + (python-indent-post-self-insert-function, python-shell-send-file) + (python-shell-completion-get-completions) + (python-shell-completion-complete-or-indent) + (python-eldoc--get-doc-at-point): Reflow docstrings. + 2014-03-14 Glenn Morris * emacs-lisp/package.el (package-menu-mode-map): @@ -35,7 +63,7 @@ 2014-03-14 Juanma Barranquero * net/socks.el (socks, socks-override-functions) - (socks-find-services-entry): FT + (socks-find-services-entry): * progmodes/hideif.el (hif-set-var, hif-nexttoken, hif-comma) (hif-find-ifdef-block): * progmodes/modula2.el (m2-indent): Fix docstring typos. diff --git a/lisp/progmodes/python.el b/lisp/progmodes/python.el index 670451e58ae..b0102c55ffd 100644 --- a/lisp/progmodes/python.el +++ b/lisp/progmodes/python.el @@ -357,7 +357,7 @@ (defmacro python-rx (&rest regexps) "Python mode specialized rx macro. -This variant of `rx' supports common python named REGEXPS." +This variant of `rx' supports common Python named REGEXPS." (let ((rx-constituents (append python-rx-constituents rx-constituents))) (cond ((null regexps) (error "No regexp")) @@ -528,7 +528,7 @@ The type returned can be `comment', `string' or `paren'." (defsubst python-syntax-count-quotes (quote-char &optional point limit) "Count number of quotes around point (max is 3). QUOTE-CHAR is the quote char to count. Optional argument POINT is -the point where scan starts (defaults to current point) and LIMIT +the point where scan starts (defaults to current point), and LIMIT is used to limit the scan." (let ((i 0)) (while (and (< i 3) @@ -683,7 +683,7 @@ AFTER-LINE.") (defun python-indent-context () "Get information on indentation context. Context information is returned with a cons with the form: - \(STATUS . START) + (STATUS . START) Where status can be any of the following symbols: @@ -963,11 +963,11 @@ variable `python-indent-current-level'. When the variable `last-command' is not equal to one of the symbols inside `python-indent-trigger-commands' and FORCE-TOGGLE -is nil it calculates possible indentation levels and saves it in -the variable `python-indent-levels'. Afterwards it sets the +is nil it calculates possible indentation levels and saves them +in the variable `python-indent-levels'. Afterwards it sets the variable `python-indent-current-level' correctly so offset is -equal to (`nth' `python-indent-current-level' -`python-indent-levels')" +equal to + (nth python-indent-current-level python-indent-levels)" (or (and (or (and (memq this-command python-indent-trigger-commands) (eq last-command this-command)) @@ -1010,14 +1010,14 @@ See `python-indent-line' for details." (defun python-indent-dedent-line-backspace (arg) "De-indent current line. Argument ARG is passed to `backward-delete-char-untabify' when -point is not in between the indentation." +point is not in between the indentation." (interactive "*p") (when (not (python-indent-dedent-line)) (backward-delete-char-untabify arg))) (put 'python-indent-dedent-line-backspace 'delete-selection 'supersede) (defun python-indent-region (start end) - "Indent a python region automagically. + "Indent a Python region automagically. Called from a program, START and END specify the region to indent." (let ((deactivate-mark nil)) @@ -1076,7 +1076,7 @@ any lines in the region are indented less than COUNT columns." (add-to-list 'debug-ignored-errors "^Can't shift all lines enough") (defun python-indent-shift-right (start end &optional count) - "Shift lines contained in region START END by COUNT columns to the left. + "Shift lines contained in region START END by COUNT columns to the right. COUNT defaults to `python-indent-offset'. If region isn't active, the current line is shifted. The shifted region includes the lines in which START and END lie." @@ -1091,10 +1091,9 @@ the lines in which START and END lie." (defun python-indent-post-self-insert-function () "Adjust indentation after insertion of some characters. -This function is intended to be added to the -`post-self-insert-hook.' If a line renders a paren alone, after -adding a char before it, the line will be re-indented -automatically if needed." +This function is intended to be added to `post-self-insert-hook.' +If a line renders a paren alone, after adding a char before it, +the line will be re-indented automatically if needed." (when (and electric-indent-mode (eq (char-before) last-command-event)) (cond @@ -1176,10 +1175,10 @@ With positive ARG search backwards, else search forwards." (defun python-nav-beginning-of-defun (&optional arg) "Move point to `beginning-of-defun'. -With positive ARG search backwards else search forward. When ARG -is nil or 0 defaults to 1. When searching backwards nested -defuns are handled with care depending on current point -position. Return non-nil if point is moved to +With positive ARG search backwards else search forward. +ARG nil or 0 defaults to 1. When searching backwards, +nested defuns are handled with care depending on current +point position. Return non-nil if point is moved to `beginning-of-defun'." (when (or (null arg) (= arg 0)) (setq arg 1)) (let ((found)) @@ -1559,7 +1558,7 @@ backward N times." (defun python-nav-backward-sexp (&optional arg) "Move backward across expressions. With ARG, do it that many times. Negative arg -N means move -backward N times." +forward N times." (interactive "^p") (or arg (setq arg 1)) (python-nav-forward-sexp (- arg))) @@ -1580,7 +1579,7 @@ backward N times." (defun python-nav-backward-sexp-safe (&optional arg) "Move backward safely across expressions. With ARG, do it that many times. Negative arg -N means move -backward N times." +forward N times." (interactive "^p") (or arg (setq arg 1)) (python-nav-forward-sexp-safe (- arg))) @@ -1640,7 +1639,7 @@ This command assumes point is not in a string or comment." (defun python-nav-backward-up-list (&optional arg) "Move backward out of one level of parentheses (or blocks). With ARG, do this that many times. -A negative argument means move backward but still to a less deep spot. +A negative argument means move forward but still to a less deep spot. This command assumes point is not in a string or comment." (interactive "^p") (or arg (setq arg 1)) @@ -1695,36 +1694,36 @@ position, else returns nil." :group 'python) (defcustom python-shell-prompt-regexp ">>> " - "Regular Expression matching top\-level input prompt of python shell. + "Regular expression matching top-level input prompt of Python shell. It should not contain a caret (^) at the beginning." :type 'string :group 'python :safe 'stringp) (defcustom python-shell-prompt-block-regexp "[.][.][.] " - "Regular Expression matching block input prompt of python shell. + "Regular expression matching block input prompt of Python shell. It should not contain a caret (^) at the beginning." :type 'string :group 'python :safe 'stringp) (defcustom python-shell-prompt-output-regexp "" - "Regular Expression matching output prompt of python shell. + "Regular expression matching output prompt of Python shell. It should not contain a caret (^) at the beginning." :type 'string :group 'python :safe 'stringp) (defcustom python-shell-prompt-pdb-regexp "[(<]*[Ii]?[Pp]db[>)]+ " - "Regular Expression matching pdb input prompt of python shell. + "Regular expression matching pdb input prompt of Python shell. It should not contain a caret (^) at the beginning." :type 'string :group 'python :safe 'stringp) (defcustom python-shell-enable-font-lock t - "Should syntax highlighting be enabled in the python shell buffer? -Restart the python shell after changing this variable for it to take effect." + "Should syntax highlighting be enabled in the Python shell buffer? +Restart the Python shell after changing this variable for it to take effect." :type 'boolean :group 'python :safe 'booleanp) @@ -1890,9 +1889,9 @@ It makes parens and quotes be treated as punctuation chars.") (define-derived-mode inferior-python-mode comint-mode "Inferior Python" "Major mode for Python inferior process. Runs a Python interpreter as a subprocess of Emacs, with Python -I/O through an Emacs buffer. Variables -`python-shell-interpreter' and `python-shell-interpreter-args' -controls which Python interpreter is run. Variables +I/O through an Emacs buffer. Variables `python-shell-interpreter' +and `python-shell-interpreter-args' control which Python +interpreter is run. Variables `python-shell-prompt-regexp', `python-shell-prompt-output-regexp', `python-shell-prompt-block-regexp', @@ -1960,8 +1959,8 @@ variable. (compilation-shell-minor-mode 1)) (defun python-shell-make-comint (cmd proc-name &optional pop internal) - "Create a python shell comint buffer. -CMD is the python command to be executed and PROC-NAME is the + "Create a Python shell comint buffer. +CMD is the Python command to be executed and PROC-NAME is the process name the comint buffer will get. After the comint buffer is created the `inferior-python-mode' is activated. When optional argument POP is non-nil the buffer is shown. When @@ -2000,8 +1999,8 @@ command used to call the interpreter and define DEDICATED, so a dedicated process for the current buffer is open. When numeric prefix arg is other than 0 or 4 do not SHOW. -Runs the hook `inferior-python-mode-hook' (after the -`comint-mode-hook' is run). \(Type \\[describe-mode] in the +Runs the hook `inferior-python-mode-hook' after +`comint-mode-hook' is run. (Type \\[describe-mode] in the process buffer for a list of commands.)" (interactive (if current-prefix-arg @@ -2021,7 +2020,7 @@ Input and output via buffer named after `python-shell-internal-get-process-name' returns. This new kind of shell is intended to be used for generic -communication related to defined configurations, the main +communication related to defined configurations; the main difference with global or dedicated shells is that these ones are attached to a configuration, not a buffer. This means that can be used for example to retrieve the sys.path and other stuff, @@ -2037,7 +2036,7 @@ startup." (python-shell-internal-get-process-name) nil t)))) (defun python-shell-get-buffer () - "Get inferior Python buffer for current buffer and return it." + "Return inferior Python buffer for current buffer." (let* ((dedicated-proc-name (python-shell-get-process-name t)) (dedicated-proc-buffer-name (format "*%s*" dedicated-proc-name)) (global-proc-name (python-shell-get-process-name nil)) @@ -2049,7 +2048,7 @@ startup." (and global-running global-proc-buffer-name)))) (defun python-shell-get-process () - "Get inferior Python process for current buffer and return it." + "Return inferior Python process for current buffer." (get-buffer-process (python-shell-get-buffer))) (defun python-shell-get-or-create-process () @@ -2216,7 +2215,7 @@ source file.") This is a wrapper over `buffer-substring' that takes care of different transformations for the code sent to be evaluated in the python shell: - 1. When Optional Argument NOMAIN is non-nil everything under an + 1. When optional argument NOMAIN is non-nil everything under an \"if __name__ == '__main__'\" block will be removed. 2. When a subregion of the buffer is sent, it takes care of appending extra empty lines so tracebacks are correct. @@ -2288,7 +2287,7 @@ the python shell: (defun python-shell-send-buffer (&optional arg) "Send the entire buffer to inferior Python process. With prefix ARG allow execution of code inside blocks delimited -by \"if __name__== '__main__':\"" +by \"if __name__== '__main__':\"." (interactive "P") (save-restriction (widen) @@ -2319,8 +2318,8 @@ When argument ARG is non-nil do not include decorators." delete) "Send FILE-NAME to inferior Python PROCESS. If TEMP-FILE-NAME is passed then that file is used for processing -instead, while internally the shell will continue to use -FILE-NAME. If DELETE is non-nil, delete the file afterwards." +instead, while internally the shell will continue to use FILE-NAME. +If DELETE is non-nil, delete the file afterwards." (interactive "fFile to send: ") (let* ((process (or process (python-shell-get-or-create-process))) (temp-file-name (when temp-file-name @@ -2420,8 +2419,7 @@ and use the following as the value of this variable: (defun python-shell-completion-get-completions (process line input) "Do completion at point for PROCESS. -LINE is used to detect the context on how to complete given -INPUT." +LINE is used to detect the context on how to complete given INPUT." (let* ((prompt ;; Get last prompt of the inferior process buffer (this ;; intentionally avoids using `comint-last-prompt' because @@ -2507,8 +2505,8 @@ using that one instead of current buffer's process." (defun python-shell-completion-complete-or-indent () "Complete or indent depending on the context. -If content before pointer is all whitespace indent. If not try -to complete." +If content before pointer is all whitespace, indent. +If not try to complete." (interactive) (if (string-match "^[[:space:]]*$" (buffer-substring (comint-line-beginning-position) @@ -2520,14 +2518,14 @@ to complete." ;;; PDB Track integration (defcustom python-pdbtrack-activate t - "Non-nil makes python shell enable pdbtracking." + "Non-nil makes Python shell enable pdbtracking." :type 'boolean :group 'python :safe 'booleanp) (defcustom python-pdbtrack-stacktrace-info-regexp "> \\([^\"(<]+\\)(\\([0-9]+\\))\\([?a-zA-Z0-9_<>]+\\)()" - "Regular Expression matching stacktrace information. + "Regular expression matching stacktrace information. Used to extract the current line and module being inspected." :type 'string :group 'python @@ -2613,9 +2611,9 @@ Argument OUTPUT is a string with the output from the comint process." (defun python-completion-complete-at-point () "Complete current symbol at point. -For this to work the best as possible you should call +For this to work as best as possible you should call `python-shell-send-buffer' from time to time so context in -inferior python process is updated properly." +inferior Python process is updated properly." (let ((process (python-shell-get-process))) (if (not process) (error "Completion needs an inferior Python process running") @@ -2660,12 +2658,12 @@ fill parens." This affects `python-fill-string' behavior with regards to triple quotes positioning. -Possible values are DJANGO, ONETWO, PEP-257, PEP-257-NN, -SYMMETRIC, and NIL. A value of NIL won't care about quotes +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: +`django': \"\"\" Process foo, return bar. @@ -2677,7 +2675,7 @@ DJANGO: If processing fails throw ProcessingError. \"\"\" -ONETWO: +`onetwo': \"\"\"Process foo, return bar.\"\"\" @@ -2688,7 +2686,7 @@ ONETWO: \"\"\" -PEP-257: +`pep-257': \"\"\"Process foo, return bar.\"\"\" @@ -2698,7 +2696,7 @@ PEP-257: \"\"\" -PEP-257-NN: +`pep-257-nn': \"\"\"Process foo, return bar.\"\"\" @@ -2707,7 +2705,7 @@ PEP-257-NN: If processing fails throw ProcessingError. \"\"\" -SYMMETRIC: +`symmetric': \"\"\"Process foo, return bar.\"\"\" @@ -3064,8 +3062,8 @@ The skeleton will be bound to python-skeleton-NAME." (defun python-check (command) "Check a Python file (default current buffer's file). -Runs COMMAND, a shell command, as if by `compile'. See -`python-check-command' for the default." +Runs COMMAND, a shell command, as if by `compile'. +See `python-check-command' for the default." (interactive (list (read-string "Check command: " (or python-check-custom-command @@ -3130,10 +3128,9 @@ Runs COMMAND, a shell command, as if by `compile'. See (defun python-eldoc--get-doc-at-point (&optional force-input force-process) "Internal implementation to get documentation at point. -If not FORCE-INPUT is passed then what -`python-info-current-symbol' returns will be used. If not -FORCE-PROCESS is passed what `python-shell-get-process' returns -is used." +If not FORCE-INPUT is passed then what `python-info-current-symbol' +returns will be used. If not FORCE-PROCESS is passed what +`python-shell-get-process' returns is used." (let ((process (or force-process (python-shell-get-process)))) (if (not process) (error "Eldoc needs an inferior Python process running") @@ -3146,9 +3143,9 @@ is used." (defun python-eldoc-function () "`eldoc-documentation-function' for Python. -For this to work the best as possible you should call +For this to work as best as possible you should call `python-shell-send-buffer' from time to time so context in -inferior python process is updated properly." +inferior Python process is updated properly." (python-eldoc--get-doc-at-point)) (defun python-eldoc-at-point (symbol) @@ -3185,15 +3182,15 @@ It must be a function with two arguments: TYPE and NAME.") It must be a function with two arguments: TYPE and NAME.") (defun python-imenu-format-item-label (type name) - "Return imenu label for single node using TYPE and NAME." + "Return Imenu label for single node using TYPE and NAME." (format "%s (%s)" name type)) (defun python-imenu-format-parent-item-label (type name) - "Return imenu label for parent node using TYPE and NAME." + "Return Imenu label for parent node using TYPE and NAME." (format "%s..." (python-imenu-format-item-label type name))) (defun python-imenu-format-parent-item-jump-label (type _name) - "Return imenu label for parent node jump using TYPE and NAME." + "Return Imenu label for parent node jump using TYPE and NAME." (if (string= type "class") "*class definition*" "*function definition*")) @@ -3210,7 +3207,7 @@ It must be a function with two arguments: TYPE and NAME.") (defun python-imenu--build-tree (&optional min-indent prev-indent tree) "Recursively build the tree of nested definitions of a node. -Arguments MIN-INDENT PREV-INDENT and TREE are internal and should +Arguments MIN-INDENT, PREV-INDENT and TREE are internal and should not be passed explicitly unless you know what you are doing." (setq min-indent (or min-indent 0) prev-indent (or prev-indent python-indent-offset)) @@ -3251,7 +3248,7 @@ not be passed explicitly unless you know what you are doing." tree))))))) (defun python-imenu-create-index () - "Return tree Imenu alist for the current python buffer. + "Return tree Imenu alist for the current Python buffer. Change `python-imenu-format-item-label-function', `python-imenu-format-parent-item-label-function', `python-imenu-format-parent-item-jump-label-function' to @@ -3264,18 +3261,19 @@ customize how labels are formatted." index)) (defun python-imenu-create-flat-index (&optional alist prefix) - "Return flat outline of the current python buffer for Imenu. -Optional Argument ALIST is the tree to be flattened, when nil + "Return flat outline of the current Python buffer for Imenu. +Optional argument ALIST is the tree to be flattened; when nil `python-imenu-build-index' is used with `python-imenu-format-parent-item-jump-label-function' `python-imenu-format-parent-item-label-function' -`python-imenu-format-item-label-function' set to (lambda (type -name) name). Optional Argument PREFIX is used in recursive calls -and should not be passed explicitly. +`python-imenu-format-item-label-function' set to + (lambda (type name) name) +Optional argument PREFIX is used in recursive calls and should +not be passed explicitly. Converts this: - \((\"Foo\" . 103) + ((\"Foo\" . 103) (\"Bar\" . 138) (\"decorator\" (\"decorator\" . 173) @@ -3285,7 +3283,7 @@ Converts this: To this: - \((\"Foo\" . 103) + ((\"Foo\" . 103) (\"Bar\" . 138) (\"decorator\" . 173) (\"decorator.wrap\" . 353) @@ -3318,9 +3316,8 @@ To this: (defun python-info-current-defun (&optional include-type) "Return name of surrounding function with Python compatible dotty syntax. Optional argument INCLUDE-TYPE indicates to include the type of the defun. -This function is compatible to be used as -`add-log-current-defun-function' since it returns nil if point is -not inside a defun." +This function can be used as the value of `add-log-current-defun-function' +since it returns nil if point is not inside a defun." (save-restriction (widen) (save-excursion @@ -3583,13 +3580,13 @@ operator." (looking-at python-nav-beginning-of-defun-regexp)))) (defun python-info-current-line-comment-p () - "Check if current line is a comment line." + "Return non-nil if current line is a comment line." (char-equal (or (char-after (+ (line-beginning-position) (current-indentation))) ?_) ?#)) (defun python-info-current-line-empty-p () - "Check if current line is empty, ignoring whitespace." + "Return non-nil if current line is empty, ignoring whitespace." (save-excursion (beginning-of-line 1) (looking-at @@ -3633,9 +3630,9 @@ Optional argument DIRECTION defines the direction to move to." (defun python-util-popn (lst n) "Return LST first N elements. -N should be an integer, when it's a natural negative number its -opposite is used. When N is bigger than the length of LST, the -list is returned as is." +N should be an integer, when negative its opposite is used. +When N is bigger than the length of LST, the list is +returned as is." (let* ((n (min (abs n))) (len (length lst)) (acc)) -- 2.39.2