From 2e330adc6c0995cb1c958dd196731b7c22a949d7 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sat, 15 Aug 2009 01:04:14 +0000 Subject: [PATCH] * progmodes/js.el: Edit docstrings throughout to follow Emacs conventions. (js-insert-and-indent): Function deleted. (js-mode-map): Don't bind keys to js-insert-and-indent. (js-beginning-of-defun): Rename from js--beginning-of-defun. (js-end-of-defun): Rename from js--end-of-defun. (js-auto-indent-flag): Variable deleted. --- lisp/ChangeLog | 13 + lisp/progmodes/js.el | 623 ++++++++++++++++++++----------------------- 2 files changed, 295 insertions(+), 341 deletions(-) diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 05b94dff1af..dbef38f6fc9 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,5 +1,18 @@ +2009-08-15 Chong Yidong + + * progmodes/js.el: Edit docstrings throughout to follow Emacs + conventions. + (js-insert-and-indent): Function deleted. + (js-mode-map): Don't bind keys to js-insert-and-indent. + (js-beginning-of-defun): Rename from js--beginning-of-defun. + (js-end-of-defun): Rename from js--end-of-defun. + (js-auto-indent-flag): Variable deleted. + 2009-08-14 Chong Yidong + * progmodes/js.el: Remove proclaim statement. Defvar + which-func-imenu-joiner-function to silence compiler. + * files.el (auto-mode-alist): Use js-mode for .js files. * progmodes/js2-mode.el: File removed. diff --git a/lisp/progmodes/js.el b/lisp/progmodes/js.el index d5f2e4965a3..5ae0a035f8f 100644 --- a/lisp/progmodes/js.el +++ b/lisp/progmodes/js.el @@ -1,4 +1,4 @@ -;;; js.el --- Major mode for editing JavaScript source text +;;; js.el --- Major mode for editing JavaScript ;; Copyright (C) 2008, 2009 Free Software Foundation, Inc. @@ -59,9 +59,7 @@ (eval-when-compile (require 'cl) (require 'comint) - (require 'ido) - ;; Swap the speed and safety values for debugging - (proclaim '(optimize (speed 3) (safety 0)))) + (require 'ido)) (defvar inferior-moz-buffer) (defvar moz-repl-name) @@ -72,55 +70,56 @@ ;;; Constants (defconst js--name-start-re "[a-zA-Z_$]" - "Matches the first character of a Javascript identifier. No grouping") + "Regexp matching the start of a JavaScript identifier, without grouping.") (defconst js--stmt-delim-chars "^;{}?:") (defconst js--name-re (concat js--name-start-re "\\(?:\\s_\\|\\sw\\)*") - "Matches a Javascript identifier. No grouping.") + "Regexp matching a JavaScript identifier, without grouping.") (defconst js--objfield-re (concat js--name-re ":") - "Matches a Javascript object field start") + "Regexp matching the start of a JavaScript object field.") (defconst js--dotted-name-re (concat js--name-re "\\(?:\\." js--name-re "\\)*") - "Matches a dot-separated sequence of Javascript names") + "Regexp matching a dot-separated sequence of JavaScript names.") (defconst js--cpp-name-re js--name-re - "Matches a C preprocessor name") + "Regexp matching a C preprocessor name.") (defconst js--opt-cpp-start "^\\s-*#\\s-*\\([[:alnum:]]+\\)" - "Regexp matching the prefix of a cpp directive including the directive -name, or nil in languages without preprocessor support. The first -submatch surrounds the directive name.") + "Regexp matching the prefix of a cpp directive. +This includes the directive name, or nil in languages without +preprocessor support. The first submatch surrounds the directive +name.") (defconst js--plain-method-re (concat "^\\s-*?\\(" js--dotted-name-re "\\)\\.prototype" "\\.\\(" js--name-re "\\)\\s-*?=\\s-*?\\(function\\)\\_>") - "Regexp matching an old-fashioned explicit prototype \"method\" - declaration. Group 1 is a (possibly-dotted) class name, group 2 - is a method name, and group 3 is the 'function' keyword." ) + "Regexp matching an explicit JavaScript prototype \"method\" declaration. +Group 1 is a (possibly-dotted) class name, group 2 is a method +name, and group 3 is the 'function' keyword." ) (defconst js--plain-class-re (concat "^\\s-*\\(" js--dotted-name-re "\\)\\.prototype" "\\s-*=\\s-*{") - "Regexp matching an old-fashioned explicit prototype \"class\" - declaration, as in Class.prototype = { method1: ...} ") + "Regexp matching a JavaScript explicit prototype \"class\" declaration. +An example of this is \"Class.prototype = { method1: ...}\".") +;; var NewClass = BaseClass.extend( (defconst js--mp-class-decl-re (concat "^\\s-*var\\s-+" "\\(" js--name-re "\\)" "\\s-*=\\s-*" "\\(" js--dotted-name-re - "\\)\\.extend\\(?:Final\\)?\\s-*(\\s-*{?\\s-*$") - "var NewClass = BaseClass.extend(") + "\\)\\.extend\\(?:Final\\)?\\s-*(\\s-*{?\\s-*$")) +;; var NewClass = Class.create() (defconst js--prototype-obsolete-class-decl-re (concat "^\\s-*\\(?:var\\s-+\\)?" "\\(" js--dotted-name-re "\\)" - "\\s-*=\\s-*Class\\.create()") - "var NewClass = Class.create()") + "\\s-*=\\s-*Class\\.create()")) (defconst js--prototype-objextend-class-decl-re-1 (concat "^\\s-*Object\\.extend\\s-*(" @@ -132,14 +131,14 @@ submatch surrounds the directive name.") "\\(" js--dotted-name-re "\\)" "\\s-*=\\s-*Object\\.extend\\s-*\(")) +;; var NewClass = Class.create({ (defconst js--prototype-class-decl-re (concat "^\\s-*\\(?:var\\s-+\\)?" "\\(" js--name-re "\\)" "\\s-*=\\s-*Class\\.create\\s-*(\\s-*" - "\\(?:\\(" js--dotted-name-re "\\)\\s-*,\\s-*\\)?{?") - "var NewClass = Class.create({") + "\\(?:\\(" js--dotted-name-re "\\)\\s-*,\\s-*\\)?{?")) -;; Parent class name(s) (yes, multiple inheritance in Javascript) are +;; Parent class name(s) (yes, multiple inheritance in JavaScript) are ;; matched with dedicated font-lock matchers (defconst js--dojo-class-decl-re (concat "^\\s-*dojo\\.declare\\s-*(\"\\(" js--dotted-name-re "\\)")) @@ -148,19 +147,19 @@ submatch surrounds the directive name.") (concat "^\\s-*Ext\\.extend\\s-*(" "\\s-*\\(" js--dotted-name-re "\\)" "\\s-*,\\s-*\\(" js--dotted-name-re "\\)") - "ExtJS class declaration (style 1)") + "Regexp matching an ExtJS class declaration (style 1).") (defconst js--extjs-class-decl-re-2 (concat "^\\s-*\\(?:var\\s-+\\)?" "\\(" js--name-re "\\)" "\\s-*=\\s-*Ext\\.extend\\s-*(\\s-*" "\\(" js--dotted-name-re "\\)") - "ExtJS class declaration (style 2)") + "Regexp matching an ExtJS class declaration (style 2).") (defconst js--mochikit-class-re (concat "^\\s-*MochiKit\\.Base\\.update\\s-*(\\s-*" "\\(" js--dotted-name-re "\\)") - "MochiKit class declaration?") + "Regexp matching a MochiKit class declaration.") (defconst js--dummy-class-style '(:name "[Automatically Generated Class]")) @@ -221,7 +220,7 @@ submatch surrounds the directive name.") :contexts (toplevel) :framework merrillpress)) - "A list of class definition styles. + "List of JavaScript class definition styles. A class definition style is a plist with the following keys: @@ -249,36 +248,34 @@ name as matched contains unless (memq framework available-frameworks) collect framework into available-frameworks finally return available-frameworks) - - "List of available frameworks symbols") + "List of available JavaScript frameworks symbols.") (defconst js--function-heading-1-re (concat "^\\s-*function\\s-+\\(" js--name-re "\\)") - "Regular expression matching the start of a function header. Match group 1 -is the name of the function.") + "Regexp matching the start of a JavaScript function header. +Match group 1 is the name of the function.") (defconst js--function-heading-2-re (concat "^\\s-*\\(" js--name-re "\\)\\s-*:\\s-*function\\_>") - "Regular expression matching the start of a function entry in - an associative array. Match group 1 is the name of the function.") + "Regexp matching the start of a function entry in an associative array. +Match group 1 is the name of the function.") (defconst js--function-heading-3-re (concat "^\\s-*\\(?:var\\s-+\\)?\\(" js--dotted-name-re "\\)" "\\s-*=\\s-*function\\_>") - "Matches a line in the form var MUMBLE = function. Match group - 1 is MUMBLE.") + "Regexp matching a line in the JavaScript form \"var MUMBLE = function\". +Match group 1 is MUMBLE.") (defconst js--macro-decl-re (concat "^\\s-*#\\s-*define\\s-+\\(" js--cpp-name-re "\\)\\s-*(") - "Regular expression matching a CPP macro definition up to the opening -parenthesis. Match group 1 is the name of the function.") + "Regexp matching a CPP macro definition, up to the opening parenthesis. +Match group 1 is the name of the function.") (defun js--regexp-opt-symbol (list) - "Like regexp-opt, but surround the optimized regular expression -with `\\\\_<' and `\\\\_>'." + "Like `regexp-opt', but surround the result with `\\\\_<' and `\\\\_>'." (concat "\\_<" (regexp-opt list t) "\\_>")) (defconst js--keyword-re @@ -292,7 +289,7 @@ with `\\\\_<' and `\\\\_>'." "super" "switch" "synchronized" "throw" "throws" "transient" "try" "typeof" "var" "void" "let" "yield" "volatile" "while" "with")) - "Regular expression matching any JavaScript keyword.") + "Regexp matching any JavaScript keyword.") (defconst js--basic-type-re (js--regexp-opt-symbol @@ -312,7 +309,7 @@ with `\\\\_<' and `\\\\_>'." "\\_" (list js--function-heading-1-re 1 font-lock-function-name-face) (list js--function-heading-2-re 1 font-lock-function-name-face)) - "Level one font lock.") + "Level one font lock keywords for `js-mode'.") (defconst js--font-lock-keywords-2 (append js--font-lock-keywords-1 @@ -322,7 +319,7 @@ with `\\\\_<' and `\\\\_>'." (list 1 'font-lock-keyword-face)) (cons js--basic-type-re font-lock-type-face) (cons js--constant-re font-lock-constant-face))) - "Level two font lock.") + "Level two font lock keywords for `js-mode'.") ;; js--pitem is the basic building block of the lexical ;; database. When one refers to a real part of the buffer, the region @@ -415,55 +412,45 @@ with `\\\\_<' and `\\\\_>'." ;; (b-end nil)) +;; The pitem we start parsing with. (defconst js--initial-pitem (make-js--pitem :paren-depth most-negative-fixnum - :type 'toplevel) - - "The pitem we start parsing with") + :type 'toplevel)) ;;; User Customization (defgroup js nil - "Customization variables for `js-mode'." + "Customization variables for JavaScript mode." :tag "JavaScript" :group 'languages) (defcustom js-indent-level 4 - "Number of spaces for each indentation step." + "Number of spaces for each indentation step in `js-mode'." :type 'integer :group 'js) (defcustom js-expr-indent-offset 0 - "Number of additional spaces used for indentation of continued -expressions. The value must be no less than minus -`js-indent-level'." + "Number of additional spaces used for indentation of continued expressions. +The value must be no less than minus `js-indent-level'." :type 'integer :group 'js) -(defcustom js-auto-indent-flag t - "Automatic indentation with punctuation characters. If non-nil, the -current line is indented when certain punctuations are inserted." - :type 'boolean - :group 'js) - (defcustom js-flat-functions nil - "Treat nested functions as if they were top-level functions for -function movement, marking, and so on." + "Treat nested functions as top-level functions in `js-mode'. +This applies to function movement, marking, and so on." :type 'boolean :group 'js) (defcustom js-comment-lineup-func #'c-lineup-C-comments - "cc-mode-style lineup function for C comments" + "Lineup function for `cc-mode-style', for C comments in `js-mode'." :type 'function :group 'js) (defcustom js-enabled-frameworks js--available-frameworks - "Select which frameworks js-mode will recognize. - -Turn off some frameworks you seldom use to improve performance. -The set of recognized frameworks can also be overriden on a -per-buffer basis." + "Frameworks recognized by `js-mode'. +To improve performance, you may turn off some frameworks you +seldom use, either globally or on a per-buffer basis." :type (cons 'set (mapcar (lambda (x) (list 'const x)) js--available-frameworks)) @@ -471,23 +458,24 @@ per-buffer basis." (defcustom js-js-switch-tabs (and (memq system-type '(darwin)) t) - "Non-nil if Emacs should display tabs while selecting them. - Useful only if the windowing system has a good mechanism for - preventing Firefox from stealing the keyboard focus." + "Whether `js-mode' should display tabs while selecting them. +This is useful only if the windowing system has a good mechanism +for preventing Firefox from stealing the keyboard focus." :type 'boolean :group 'js) (defcustom js-js-tmpdir "~/.emacs.d/js/js" - "Temporary directory used for communicating with Mozilla. It - must be readable and writable by both Mozilla and Emacs." + "Temporary directory used by `js-mode' to communicate with Mozilla. +This directory must be readable and writable by both Mozilla and +Emacs." :type 'directory :group 'js) (defcustom js-js-timeout 5 - "Wait this many seconds for a reply from Mozilla when executing -commands. Increase this value if you are getting timeout -messages." + "Reply timeout for executing commands in Mozilla via `js-mode'. +The value is given in seconds. Increase this value if you are +getting timeout messages." :type 'integer :group 'js) @@ -495,14 +483,10 @@ messages." (defvar js-mode-map (let ((keymap (make-sparse-keymap))) - (mapc (lambda (key) - (define-key keymap key #'js-insert-and-indent)) - '("+" "-" "*" "{" "}" "(" ")" ":" ";" ",")) (define-key keymap [(control ?c) (meta ?:)] #'js-eval) (define-key keymap [(control ?c) (control ?j)] #'js-set-js-context) (define-key keymap [(control meta ?x)] #'js-eval-defun) (define-key keymap [(meta ?.)] #'js-find-symbol) - (easy-menu-define nil keymap "Javascript Menu" '("Javascript" ["Select new Mozilla context…" js-set-js-context @@ -510,26 +494,9 @@ messages." ["Evaluate expression in Mozilla context…" js-eval (fboundp #'inferior-moz-process)] ["Send current function to Mozilla…" js-eval-defun - (fboundp #'inferior-moz-process)] - ) - ) - + (fboundp #'inferior-moz-process)])) keymap) - "Keymap for js-mode") - -(defun js-insert-and-indent (key) - "Runs the command bound to KEY in the global keymap, and if -we're not in a string or comment, indents the current line." - (interactive (list (this-command-keys))) - (call-interactively (lookup-key (current-global-map) key)) - (let ((syntax (save-restriction (widen) (syntax-ppss)))) - (when (or (and (not (nth 8 syntax)) - js-auto-indent-flag) - (and (nth 4 syntax) - (eq (current-column) - (1+ (current-indentation))))) - - (indent-according-to-mode)))) + "Keymap for `js-mode'.") ;;; Syntax table and parsing @@ -538,50 +505,50 @@ we're not in a string or comment, indents the current line." (c-populate-syntax-table table) (modify-syntax-entry ?$ "_" table) table) - "Syntax table used in JS mode.") + "Syntax table for `js-mode'.") (defvar js--quick-match-re nil - "Autogenerated regular expression to match buffer constructs") + "Autogenerated regexp used by `js-mode' to match buffer constructs.") (defvar js--quick-match-re-func nil - "Autogenerated regular expression to match buffer constructs -and functions") + "Autogenerated regexp used by `js-mode' to match constructs and functions.") (make-variable-buffer-local 'js--quick-match-re) (make-variable-buffer-local 'js--quick-match-re-func) (defvar js--cache-end 1 - "Last place in the buffer the function cache is valid") + "Last valid buffer position for the `js-mode' function cache.") (make-variable-buffer-local 'js--cache-end) (defvar js--last-parse-pos nil - "Last place we parsed up to in js--ensure-cache") + "Latest parse position reached by `js--ensure-cache'.") (make-variable-buffer-local 'js--last-parse-pos) (defvar js--state-at-last-parse-pos nil - "pstate at js--last-parse-pos") + "Parse state at `js--last-parse-pos'.") (make-variable-buffer-local 'js--state-at-last-parse-pos) (defun js--flatten-list (list) (loop for item in list nconc (cond ((consp item) (js--flatten-list item)) - (item (list item))))) (defun js--maybe-join (prefix separator suffix &rest list) - "If LIST contains any element that is not nil, return its -non-nil elements, separated by SEPARATOR, prefixed by PREFIX, and -ended with SUFFIX as with `concat'. Otherwise, if LIST is empty, -return nil. If any element in LIST is itself a list, flatten that + "Helper function for `js--update-quick-match-re'. +If LIST contains any element that is not nil, return its non-nil +elements, separated by SEPARATOR, prefixed by PREFIX, and ended +with SUFFIX as with `concat'. Otherwise, if LIST is empty, return +nil. If any element in LIST is itself a list, flatten that element." (setq list (js--flatten-list list)) (when list (concat prefix (mapconcat #'identity list separator) suffix))) (defun js--update-quick-match-re () - "Update js--quick-match-re based on the current set of -enabled frameworks" + "Internal function used by `js-mode' for caching buffer constructs. +This updates `js--quick-match-re', based on the current set of +enabled frameworks." (setq js--quick-match-re (js--maybe-join "^[ \t]*\\(?:" "\\|" "\\)" @@ -631,9 +598,9 @@ enabled frameworks" (concat "function\\|" js--quick-match-re))) (defun js--forward-text-property (propname) - "Move over the next value of PROPNAME in the buffer. If found, -return that value and leave point after the character having that -value, otherwise return nil and leave point at EOB." + "Move over the next value of PROPNAME in the buffer. +If found, return that value and leave point after the character +having that value; otherwise, return nil and leave point at EOB." (let ((next-value (get-text-property (point) propname))) (if next-value (forward-char) @@ -647,9 +614,10 @@ value, otherwise return nil and leave point at EOB." next-value)) (defun js--backward-text-property (propname) - "Move over the previous value of PROPNAME in the buffer. If found, -return that value and leave point just before the character that -has that value, otherwise return nil and leave point at BOB." + "Move over the previous value of PROPNAME in the buffer. +If found, return that value and leave point just before the +character that has that value, otherwise return nil and leave +point at BOB." (unless (bobp) (let ((prev-value (get-text-property (1- (point)) propname))) (if prev-value @@ -675,7 +643,7 @@ has that value, otherwise return nil and leave point at BOB." (js--forward-pstate)) (defun js--re-search-forward-inner (regexp &optional bound count) - "Auxiliary function for `js--re-search-forward'." + "Helper function for `js--re-search-forward'." (let ((parse) str-terminator (orig-macro-end (save-excursion @@ -706,14 +674,12 @@ has that value, otherwise return nil and leave point at BOB." (defun js--re-search-forward (regexp &optional bound noerror count) - "Search forward but ignore strings, cpp macros, and comments. -Invokes `re-search-forward' but treats the buffer as if strings, -cpp macros, and comments have been removed. - -If invoked while inside a macro, treat the contents of the macro -as normal text. + "Search forward, ignoring strings, cpp macros, and comments. +This function invokes `re-search-forward', but treats the buffer +as if strings, cpp macros, and comments have been removed. -" +If invoked while inside a macro, it treats the contents of the +macro as normal text." (let ((saved-point (point)) (search-expr (cond ((null count) @@ -764,12 +730,13 @@ as normal text. (defun js--re-search-backward (regexp &optional bound noerror count) - "Search backward but ignore strings, preprocessor macros, and -comments. Invokes `re-search-backward' but treats the buffer as -if strings, preprocessor macros, and comments have been removed. + "Search backward, ignoring strings, preprocessor macros, and comments. + +This function invokes `re-search-backward' but treats the buffer +as if strings, preprocessor macros, and comments have been +removed. -If inside a macro when called, treat the macro as normal text. -" +If invoked while inside a macro, treat the macro as normal text." (let ((saved-point (point)) (search-expr (cond ((null count) @@ -786,8 +753,9 @@ If inside a macro when called, treat the macro as normal text. (error (error-message-string err))))))) (defun js--forward-expression () - "Move forward over a whole expression. Doesn't move over -expressions continued across lines, but we don't actually care" + "Move forward over a whole JavaScript expression. +This function doesn't move over expressions continued across +lines." (loop ;; non-continued case; simplistic, but good enough? do (loop until (or (eolp) @@ -802,11 +770,12 @@ expressions continued across lines, but we don't actually care" (js--continued-expression-p))))) (defun js--forward-function-decl () - "Move forward over a function declaration with point at the -'function' keyword. Return non-nil if this is a -syntactically-correct non-expression function, nil otherwise. -Specifically, return the name of the function, or t if the name -could not be determined." + "Move forward over a JavaScript function declaration. +This puts point at the 'function' keyword. + +If this is a syntactically-correct non-expression function, +return the name of the function, or t if the name could not be +determined. Otherwise, return nil." (assert (looking-at "\\_")) (let ((name t)) (forward-word) @@ -822,11 +791,10 @@ could not be determined." name))))) (defun js--function-prologue-beginning (&optional pos) - "Return the start of the function prologue that contains POS, -or nil if we're not in a function prologue. A function prologue -is everything from start of the definition up to and including -the opening brace. POS defaults to point." - + "Return the start of the JavaScript function prologue containing POS. +A function prologue is everything from start of the definition up +to and including the opening brace. POS defaults to point. +If POS is not in a function prologue, return nil." (let (prologue-begin) (save-excursion (if pos @@ -853,9 +821,10 @@ the opening brace. POS defaults to point." (or prologue-begin (match-beginning 0)))))) (defun js--beginning-of-defun-raw () - "Internal helper for js--beginning-of-defun. Go to -previous defun-beginning and return the parse state for it, or -nil if we went all the way back to bob and don't find anything." + "Helper function for `js-beginning-of-defun'. +Go to previous defun-beginning and return the parse state for it, +or nil if we went all the way back to bob and don't find +anything." (js--ensure-cache) (let (pstate) (while (and (setq pstate (js--backward-pstate)) @@ -863,8 +832,9 @@ nil if we went all the way back to bob and don't find anything." (and (not (bobp)) pstate))) (defun js--pstate-is-toplevel-defun (pstate) - "If PSTATE represents a non-empty top-level defun, return the -top-most pitem. Otherwise, return nil." + "Helper function for `js--beginning-of-defun-nested'. +If PSTATE represents a non-empty top-level defun, return the +top-most pitem. Otherwise, return nil." (loop for pitem in pstate with func-depth = 0 with func-pitem @@ -874,9 +844,8 @@ top-most pitem. Otherwise, return nil." finally return (if (eq func-depth 1) func-pitem))) (defun js--beginning-of-defun-nested () - "Internal helper for js--beginning-of-defun. Returns the -pitem of the function we went to the beginning of." - + "Helper function for `js--beginning-of-defun'. +Return the pitem of the function we went to the beginning of." (or ;; Look for the smallest function that encloses point... (loop for pitem in (js--parse-state-at-point) @@ -894,22 +863,20 @@ pitem of the function we went to the beginning of." and return it))) (defun js--beginning-of-defun-flat () - "Internal helper for js--beginning-of-defun" - + "Helper function for `js-beginning-of-defun'." (let ((pstate (js--beginning-of-defun-raw))) (when pstate (goto-char (js--pitem-h-begin (car pstate)))))) -(defun js--beginning-of-defun (&optional arg) - "Used as beginning-of-defun-function" - +(defun js-beginning-of-defun (&optional arg) + "Value of `beginning-of-defun-function' for `js-mode'." (setq arg (or arg 1)) (while (and (not (eobp)) (< arg 0)) (incf arg) (when (and (not js-flat-functions) (or (eq (js-syntactic-context) 'function) (js--function-prologue-beginning))) - (js--end-of-defun)) + (js-end-of-defun)) (if (js--re-search-forward "\\_" nil t) @@ -933,8 +900,8 @@ pitem of the function we went to the beginning of." (js--beginning-of-defun-nested)))))) (defun js--flush-caches (&optional beg ignored) - "Flush syntax cache info after position BEG. BEG defaults to -point-min, flushing the entire cache." + "Flush the `js-mode' syntax cache after position BEG. +BEG defaults to point-min, meaning to flush the entire cache." (interactive) (setq beg (or beg (save-restriction (widen) (point-min)))) (setq js--cache-end (min js--cache-end beg))) @@ -955,14 +922,13 @@ point-min, flushing the entire cache." ;; that assumption holds. (cons (js--pitem-add-child (second open-items) top-item) (cddr open-items))))) - open-items) (defmacro js--ensure-cache--update-parse () - "Helper for use inside js--ensure-cache. Updates parsing -information up to point. Refers to parse, prev-parse-point, -goal-point, and open-items bound lexically in the body of -`js--ensure-cache'." + "Helper function for `js--ensure-cache'. +Update parsing information up to point, referring to parse, +prev-parse-point, goal-point, and open-items bound lexically in +the body of `js--ensure-cache'." `(progn (setq goal-point (point)) (goto-char prev-parse-point) @@ -1001,9 +967,9 @@ goal-point, and open-items bound lexically in the body of (pp prop)))) (defun js--split-name (string) - "Splits a name into its dot-separated parts. Also removes any -prototype parts from the split name (unless the name is just -\"prototype\" to start with, that is)." + "Split a JavaScript name into its dot-separated parts. +This also removes any prototype parts from the split name (unless +the name is just \"prototype\" to start with)." (let ((name (save-match-data (split-string string "\\." t)))) (unless (and (= (length name) 1) @@ -1011,17 +977,18 @@ prototype parts from the split name (unless the name is just (setq name (remove "prototype" name))))) -(defvar js--guess-function-name-start nil - "Secondary out-variable for js--guess-function-name") +(defvar js--guess-function-name-start nil) (defun js--guess-function-name (position) - "Guess the name of the function at POSITION, which should be -the just after the end of the word 'function'. Return the name of -the function or nil if the name could not be guessed. Clobbers -match data. If in guessing the function name we find the preamble -begins earlier than expected, set `js--guess-function-name-start' -to that position, otherwise set that variable to nil." - + "Guess the name of the JavaScript function at POSITION. +POSITION should be just after the end of the word \"function\". +Return the name of the function, or nil if the name could not be +guessed. + +This function clobbers match data. If we find the preamble +begins earlier than expected while guessing the function name, +set `js--guess-function-name-start' to that position; otherwise, +set that variable to nil." (setq js--guess-function-name-start nil) (save-excursion (goto-char position) @@ -1206,7 +1173,7 @@ LIMIT defaults to point." ))))) (defun js--end-of-defun-flat () - "Internal helper for js--end-of-defun" + "Helper function for `js-end-of-defun'." (loop while (js--re-search-forward "}" nil t) do (js--ensure-cache) if (get-text-property (1- (point)) 'js--pend) @@ -1215,7 +1182,7 @@ LIMIT defaults to point." finally do (goto-char (point-max)))) (defun js--end-of-defun-nested () - "Internal helper for js--end-of-defun" + "Helper function for `js-end-of-defun'." (message "test") (let* (pitem (this-end (save-excursion @@ -1240,16 +1207,16 @@ LIMIT defaults to point." ;; ... or eob. (goto-char (point-max)))))) -(defun js--end-of-defun (&optional arg) - "Used as end-of-defun-function" +(defun js-end-of-defun (&optional arg) + "Value of `end-of-defun-function' for `js-mode'." (setq arg (or arg 1)) (while (and (not (bobp)) (< arg 0)) (let (orig-pos (point)) (incf arg) - (js--beginning-of-defun) - (js--beginning-of-defun) + (js-beginning-of-defun) + (js-beginning-of-defun) (unless (bobp) - (js--end-of-defun)))) + (js-end-of-defun)))) (while (> arg 0) (decf arg) @@ -1287,7 +1254,7 @@ LIMIT defaults to point." nil)))) (defun js--backward-syntactic-ws (&optional lim) - "Simple implementation of `c-backward-syntactic-ws'" + "Simple implementation of `c-backward-syntactic-ws' for `js-mode'." (save-restriction (when lim (narrow-to-region lim (point-max))) @@ -1302,7 +1269,7 @@ LIMIT defaults to point." (setq pos (point))))))))) (defun js--forward-syntactic-ws (&optional lim) - "Simple implementation of `c-forward-syntactic-ws'" + "Simple implementation of `c-forward-syntactic-ws' for `js-mode'." (save-restriction (when lim (narrow-to-region (point-min) lim)) (let ((pos (point))) @@ -1315,8 +1282,8 @@ LIMIT defaults to point." pos (setq pos (point))))))))) +;; Like (up-list -1), but only considers lists that end nearby" (defun js--up-nearby-list () - "Like (up-list -1), but only considers lists that end nearby" (save-restriction ;; Look at a very small region so our compuation time doesn't ;; explode in pathological cases. @@ -1324,7 +1291,7 @@ LIMIT defaults to point." (up-list -1))) (defun js--inside-param-list-p () - "Return non-nil iff point is inside a function parameter list." + "Return non-nil iff point is in a function parameter list." (ignore-errors (save-excursion (js--up-nearby-list) @@ -1335,8 +1302,7 @@ LIMIT defaults to point." (looking-at "function")))))))) (defun js--inside-dojo-class-list-p () - "Return non-nil iff point is inside a Dojo multiple-inheritance -class block." + "Return non-nil iff point is in a Dojo multiple-inheritance class block." (ignore-errors (save-excursion (js--up-nearby-list) @@ -1360,10 +1326,9 @@ class block." ;;; Font Lock (defun js--make-framework-matcher (framework &rest regexps) - "Create a byte-compiled function that only matches the given -regular expressions (that concatenation of REGEXPS) if FRAMEWORK -is in js-enabled-frameworks" - + "Helper function for building `js--font-lock-keywords'. +Create a byte-compiled function for matching a concatenation of +REGEXPS, but only if FRAMEWORK is in `js-enabled-frameworks'." (setq regexps (apply #'concat regexps)) (byte-compile `(lambda (limit) @@ -1374,11 +1339,10 @@ is in js-enabled-frameworks" (make-variable-buffer-local 'js--tmp-location) (defun js--forward-destructuring-spec (&optional func) - "Move forward over a destructuring spec. If FUNC is supplied, -call it with no arguments before every variable name in the spec. -Return true iff this was actually a spec. FUNC must preserve the -match data." - + "Move forward over a JavaScript destructuring spec. +If FUNC is supplied, call it with no arguments before every +variable name in the spec. Return true iff this was actually a +spec. FUNC must preserve the match data." (case (char-after) (?\[ (forward-char) @@ -1423,11 +1387,10 @@ match data." t)))) (defun js--variable-decl-matcher (limit) - "Font-lock matcher for variable names in a variable -declaration. This is a cc-mode-style matcher that *always* fails, -from the point of view of font-lock. It applies highlighting -directly with `font-lock-apply-higlight'." - + "Font-lock matcher for variable names in a variable declaration. +This is a cc-mode-style matcher that *always* fails, from the +point of view of font-lock. It applies highlighting directly with +`font-lock-apply-higlight'." (condition-case nil (save-restriction (narrow-to-region (point-min) limit) @@ -1580,8 +1543,7 @@ directly with `font-lock-apply-higlight'." (end-of-line)) '(end-of-line) '(0 font-lock-variable-name-face)))) - - "Level three font lock.") + "Level three font lock for `js-mode'.") (defun js--inside-pitem-p (pitem) "Return whether point is inside the given pitem's header or body" @@ -1594,10 +1556,10 @@ directly with `font-lock-apply-higlight'." (> (js--pitem-b-end pitem) (point))))) (defun js--parse-state-at-point () - "Get a list of js--pitem instances that apply to point, -most specific first. In the worst case, the current toplevel -instance will be returned." - + "Parse the JavaScript program state at point. +Return a list of `js--pitem' instances that apply to point, most +specific first. In the worst case, the current toplevel instance +will be returned." (save-excursion (save-restriction (widen) @@ -1618,19 +1580,18 @@ instance will be returned." pstate)))) (defun js--syntactic-context-from-pstate (pstate) - "Return the syntactic context corresponding to PSTATE" + "Return the JavaScript syntactic context corresponding to PSTATE." (let ((type (js--pitem-type (car pstate)))) (cond ((memq type '(function macro)) type) - ((consp type) 'class) - (t 'toplevel)))) (defun js-syntactic-context () - "Get the current syntactic context of point. When called -interatively, also display a message with that context." + "Return the JavaScript syntactic context at point. +When called interatively, also display a message with that +context." (interactive) (let* ((syntactic-context (js--syntactic-context-from-pstate (js--parse-state-at-point)))) @@ -1641,7 +1602,8 @@ interatively, also display a message with that context." syntactic-context)) (defun js--class-decl-matcher (limit) - "Fontifies according to js--class-styles" + "Font lock function used by `js-mode'. +This performs fontification according to `js--class-styles'." (loop initially (js--ensure-cache limit) while (re-search-forward js--quick-match-re limit t) for orig-end = (match-end 0) @@ -1663,22 +1625,23 @@ interatively, also display a message with that context." '(js--font-lock-keywords-3 js--font-lock-keywords-1 js--font-lock-keywords-2 js--font-lock-keywords-3) - "See `font-lock-keywords'.") + "Font lock keywords for `js-mode'. See `font-lock-keywords'.") ;; XXX: Javascript can continue a regexp literal across lines so long ;; as the newline is escaped with \. Account for that in the regexp ;; below. (defconst js--regexp-literal "[=(,:]\\(?:\\s-\\|\n\\)*\\(/\\)\\(?:\\\\/\\|[^/*]\\)\\(?:\\\\/\\|[^/]\\)*\\(/\\)" - "Match a regular expression literal. Match groups 1 and 2 are -the characters forming the beginning and end of the literal") + "Regexp matching a JavaScript regular expression literal. +Match groups 1 and 2 are the characters forming the beginning and +end of the literal.") ;; we want to match regular expressions only at the beginning of ;; expressions -(defconst js--font-lock-syntactic-keywords +(defconst js-font-lock-syntactic-keywords `((,js--regexp-literal (1 "|") (2 "|"))) - "Highlighting of regular expressions. See also the variable - `font-lock-keywords'.") + "Syntactic font lock keywords matching regexps in JavaScript. +See `font-lock-keywords'.") ;;; Indentation @@ -1686,19 +1649,16 @@ the characters forming the beginning and end of the literal") (js--regexp-opt-symbol '("catch" "do" "else" "finally" "for" "if" "try" "while" "with" "each")) - "Regular expression matching keywords that are optionally - followed by an opening brace.") + "Regexp matching keywords optionally followed by an opening brace.") (defconst js--indent-operator-re (concat "[-+*/%<>=&^|?:.]\\([^-+*/]\\|$\\)\\|" (js--regexp-opt-symbol '("in" "instanceof"))) - "Regular expression matching operators that affect indentation - of continued expressions.") + "Regexp matching operators that affect indentation of continued expressions.") (defun js--looking-at-operator-p () - "Return non-nil if text after point is an operator (that is not -a comma)." + "Return non-nil if point is on a JavaScript operator, other than a comma." (save-match-data (and (looking-at js--indent-operator-re) (or (not (looking-at ":")) @@ -1708,7 +1668,7 @@ a comma)." (defun js--continued-expression-p () - "Returns non-nil if the current line continues an expression." + "Return non-nil if the current line continues an expression." (save-excursion (back-to-indentation) (or (js--looking-at-operator-p) @@ -1724,10 +1684,10 @@ a comma)." (defun js--end-of-do-while-loop-p () - "Returns non-nil if word after point is `while' of a do-while -statement, else returns nil. A braceless do-while statement -spanning several lines requires that the start of the loop is -indented to the same column as the current line." + "Return non-nil if point is on the \"while\" of a do-while statement. +Otherwise, return nil. A braceless do-while statement spanning +several lines requires that the start of the loop is indented to +the same column as the current line." (interactive) (save-excursion (save-match-data @@ -1749,9 +1709,10 @@ indented to the same column as the current line." (defun js--ctrl-statement-indentation () - "Returns the proper indentation of the current line if it -starts the body of a control statement without braces, else -returns nil." + "Helper function for `js--proper-indentation'. +Return the proper indentation of the current line if it starts +the body of a control statement without braces; otherwise, return +nil." (save-excursion (back-to-indentation) (when (save-excursion @@ -1811,35 +1772,30 @@ returns nil." (t 0)))) (defun js-indent-line () - "Indent the current line as JavaScript source text." + "Indent the current line as JavaScript." (interactive) (save-restriction (widen) (let* ((parse-status (save-excursion (syntax-ppss (point-at-bol)))) (offset (- (current-column) (current-indentation)))) - (indent-line-to (js--proper-indentation parse-status)) (when (> offset 0) (forward-char offset))))) ;;; Filling (defun js-c-fill-paragraph (&optional justify) - "Fill the paragraph with c-fill-paragraph" + "Fill the paragraph with `c-fill-paragraph'." (interactive "*P") - (flet ((c-forward-sws (&optional limit) (js--forward-syntactic-ws limit)) - (c-backward-sws (&optional limit) (js--backward-syntactic-ws limit)) - (c-beginning-of-macro (&optional limit) (js--beginning-of-macro limit))) - (let ((fill-paragraph-function 'c-fill-paragraph)) (c-fill-paragraph justify)))) @@ -1869,11 +1825,10 @@ returns nil." (plist-get type :name))))) (defun js--make-merged-item (item child name-parts) - "Internal helper for js--splice-into-items. Return a new -item that is the result of merging CHILD into ITEM. NAME-PARTS is -a list of parts of the name of CHILD that we haven't consumed -yet." - + "Helper function for `js--splice-into-items'. +Return a new item that is the result of merging CHILD into +ITEM. NAME-PARTS is a list of parts of the name of CHILD that we +haven't consumed yet." (js--debug "js--make-merged-item: {%s} into {%s}" (js--pitem-format child) (js--pitem-format item)) @@ -1915,18 +1870,17 @@ yet." (cdr item))) (defun js--pitem-strname (pitem) - "Last part of the name of PITEM as a string or symbol" + "Last part of the name of PITEM, as a string or symbol." (let ((name (js--pitem-name pitem))) (if (consp name) (car (last name)) name))) (defun js--splice-into-items (items child name-parts) - "Non-destructively inserts CHILD into the item list ITEMS in -the proper place as given by NAME-PARTS. If a class doesn't -exist in the tree, create it. Return the new items list. -NAME-PARTS is a list of strings given the broken-down class -name of the item to insert." + "Splice CHILD into the `js--pitem' ITEMS at NAME-PARTS. +If a class doesn't exist in the tree, create it. Return the new +items list. NAME-PARTS is a list of strings given the +broken-down class name of the item to insert." (let ((top-name (car name-parts)) (item-ptr items) @@ -2001,9 +1955,7 @@ name of the item to insert." items)))) (defun js--pitem-add-child (pitem child) - "Copy js--pitem PITEM and while copying, push CHILD onto -its list of children." - + "Copy `js--pitem' PITEM, and push CHILD onto its list of children." (assert (integerp (js--pitem-h-begin child))) (assert (if (consp (js--pitem-name child)) (loop for part in (js--pitem-name child) @@ -2039,13 +1991,13 @@ its list of children." (cdr pitem))) (defun js--maybe-make-marker (location) - "Make LOCATION into a marker if imenu-use-markers" + "Return a marker for LOCATION if `imenu-use-markers' is non-nil." (if imenu-use-markers (set-marker (make-marker) location) location)) (defun js--pitems-to-imenu (pitems unknown-ctr) - "Convert list of pitems PITEMS to imenu format" + "Convert PITEMS, a list of `js--pitem' structures, to imenu format." (let (imenu-items pitem pitem-type pitem-name subitems) @@ -2086,7 +2038,7 @@ its list of children." imenu-items)) (defun js--imenu-create-index () - "Creates an imenu index for the current buffer" + "Return an imenu index for the current buffer." (save-excursion (save-restriction (widen) @@ -2111,6 +2063,9 @@ its list of children." (car (js--pitem-children state)) unknown-ctr)))))) +;; Silence the compiler. +(defvar which-func-imenu-joiner-function) + (defun js--which-func-joiner (parts) (mapconcat #'identity parts ".")) @@ -2131,10 +2086,10 @@ its list of children." (puthash name2 (cdr item) symbols)))) (defun js--get-all-known-symbols () - "Get a hash table of all relevant Javascript symbols across all -js-mode buffers. Each key is the name of a symbol (possibly -disambiguated with , where N > 1), and each value is a marker -giving the location of that symbol." + "Return a hash table of all Javascript symbols. +This searches all existing `js-mode' buffers. Each key is the +name of a symbol (possibly disambiguated with , where N > 1), +and each value is a marker giving the location of that symbol." (loop with symbols = (make-hash-table :test 'equal) with imenu-use-markers = t for buffer being the buffers @@ -2148,15 +2103,12 @@ giving the location of that symbol." "History of entered Javascript symbols") (defun js--read-symbol (symbols-table prompt &optional initial-input) - "Read a symbol from SYMBOLS-TABLE, which is a hash table like -the one from `js--get-all-known-symbols'. Return value is a -cons of (SYMBOL-NAME . LOCATION), where SYMBOL-NAME is a string -and LOCATION is a marker. - -Prompt is PROMPT. - -If INITIAL-INPUT is not nil, use it as the initial input" - + "Helper function for `js-find-symbol'. +Read a symbol from SYMBOLS-TABLE, which is a hash table like the +one from `js--get-all-known-symbols', using prompt PROMPT and +initial input INITIAL-INPUT. Return a cons of (SYMBOL-NAME +. LOCATION), where SYMBOL-NAME is a string and LOCATION is a +marker." (unless ido-mode (ido-mode t) (ido-mode nil)) @@ -2179,10 +2131,10 @@ If INITIAL-INPUT is not nil, use it as the initial input" (buffer-substring (car bounds) (cdr bounds))))) (defun js-find-symbol (&optional arg) - "Jump to a Javascript symbol we read in from the user. With -prefix argument, restrict symbols to those from the current -buffer. Pushes a mark onto the tag ring just like `find-tag'." - + "Read a Javascript symbol and jump to it. +With a prefix argument, restrict symbols to those from the +current buffer. Pushes a mark onto the tag ring just like +`find-tag'." (interactive "P") (let (symbols marker) (if (not arg) @@ -2210,10 +2162,10 @@ buffer. Pushes a mark onto the tag ring just like `find-tag'." (defun js--wait-for-matching-output (process regexp timeout &optional start) - "Wait TIMEOUT seconds for PROCESS to output something that -matches REGEXP. On timeout, return nil. On success, return t with -match data set. If START is non-nil, look for output starting -from START. Otherwise, use the current value of `process-mark'." + "Wait TIMEOUT seconds for PROCESS to output a match for REGEXP. +On timeout, return nil. On success, return t with match data +set. If START is non-nil, look for output starting from START. +Otherwise, use the current value of `process-mark'." (with-current-buffer (process-buffer process) (loop with start-pos = (or start (marker-position (process-mark process))) @@ -2243,13 +2195,12 @@ from START. Otherwise, use the current value of `process-mark'." "Maps Elisp Javascript proxy objects to their Javascript IDs.") (defvar js--js-process nil - "The last MozRepl process object we saw") + "The most recent MozRepl process object.") (defvar js--js-gc-idle-timer nil - "Idle timer for cleaning up JS object references") + "Idle timer for cleaning up JS object references.") -(defvar js--js-last-gcs-done nil - "Last number of gcs we GCed with") +(defvar js--js-last-gcs-done nil) (defconst js--moz-interactor (replace-regexp-in-string @@ -2564,11 +2515,10 @@ from START. Otherwise, use the current value of `process-mark'." "String to set MozRepl up into a simple-minded evaluation mode") (defun js--js-encode-value (x) - "Marshall the given value for JS. Strings and numbers get -JSON-encoded. Lists (including nil) are made into Javascript -array literals and their contents encoded with -js--js-encode-value." - + "Marshall the given value for JS. +Strings and numbers are JSON-encoded. Lists (including nil) are +made into Javascript array literals and their contents encoded +with `js--js-encode-value'." (cond ((stringp x) (json-encode-string x)) ((numberp x) (json-encode-number x)) ((symbolp x) (format "{objid:%S}" (symbol-name x))) @@ -2661,7 +2611,7 @@ js--js-encode-value." (eval-and-compile (defun js--optimize-arglist (arglist) - "Convert immediate js< and js! references to deferred ones" + "Convert immediate js< and js! references to deferred ones." (loop for item in arglist if (eq (car-safe item) 'js<) collect (append (list 'list ''js--funcall @@ -2703,7 +2653,7 @@ js--js-encode-value." (js< "Components" "interfaces" ,interface-name))) (defmacro with-js (&rest forms) - "Runs FORMS with the Mozilla repl set up for js commands. + "Run FORMS with the Mozilla repl set up for js commands. Inside the lexical scope of `with-js', `js?', `js!', `js-new', `js-eval', `js-list', `js<', `js>', `js-get-service', `js-create-instance', and `js-qi' are defined." @@ -2765,9 +2715,8 @@ Inside the lexical scope of `with-js', `js?', `js!', (js--js-leave-repl)))) (defvar js--js-array-as-list nil -"If bound to t and a function returns an Array, return the -elements of that Array as a list instead of returning the whole -Array as a JS symbol" ) + "Whether to listify any Array returned by a Mozilla function. +If nil, the whole Array is treated as a JS symbol.") (defun js--js-decode-retval (result) (ecase (intern (first result)) @@ -2789,12 +2738,13 @@ Array as a JS symbol" ) (defun js--js-funcall (function &rest arguments) "Call the Mozilla function FUNCTION with arguments ARGUMENTS. If function is a string, look it up as a property on the global -object and use the global object for `this'; if FUNCTION is a -list with one element, use that element as the function with the -global object for `this', except that if that single element is a -string, look it up on the global object. If FUNCTION is a list -with more than one argument, use the list up to the last value as -a property descriptor and the last argument as a function." +object and use the global object for `this'. +If FUNCTION is a list with one element, use that element as the +function with the global object for `this', except that if that +single element is a string, look it up on the global object. +If FUNCTION is a list with more than one argument, use the list +up to the last value as a property descriptor and the last +argument as a function." (with-js (let ((argstr (js--js-encode-value @@ -2818,10 +2768,8 @@ a property descriptor and the last argument as a function." (js--js-decode-retval result)))))) (defun js--js-new (constructor &rest arguments) - "Call CONSTRUCTOR as a constructor (as with new), with the -given arguments ARGUMENTS. CONSTRUCTOR is a JS handle, a string, -or a list of these things." - + "Call CONSTRUCTOR as a constructor, with arguments ARGUMENTS. +CONSTRUCTOR is a JS handle, a string, or a list of these things." (apply #'js--js-funcall '(interactor "_callNew") constructor arguments)) @@ -2830,9 +2778,7 @@ or a list of these things." (js--js-funcall '(interactor "_callEval") thisobj js)) (defun js--js-list (&rest arguments) - "Return a Lisp array that is the result of evaluating each of - the elements of ARGUMENTS" - + "Return a Lisp array resulting from evaluating each of ARGUMENTS." (let ((js--js-array-as-list t)) (apply #'js--js-funcall '(interactor "_mkArray") arguments))) @@ -2884,29 +2830,25 @@ With argument, run even if no intervening GC has happened." (run-with-idle-timer 30 t #'js-gc) (defun js-eval (js) - "Evaluate the Javascript contained in JS and return the -JSON-decoded result. eval must be called using this function -because it is special to the Javascript interpreter." + "Evaluate the JavaScript in JS and return JSON-decoded result." (interactive "MJavascript to evaluate: ") (with-js (let* ((content-window (js--js-content-window (js--get-js-context))) (result (js-eval content-window js))) - (when (interactive-p) (message "%s" (js! "String" result))) result))) (defun js--get-tabs () - "Enumerate all the contexts available. Each one is a list: - - The list is (TITLE URL BROWSER TAB TABBROWSER) for content documents - The list is (TITLE URL WINDOW) for windows - - All tabs of a given window are grouped together. The most - recent window is first. Within each window, the tabs are - returned left-to-right. -" + "Enumerate all JavaScript contexts available. +Each context is a list: + (TITLE URL BROWSER TAB TABBROWSER) for content documents + (TITLE URL WINDOW) for windows + +All tabs of a given window are grouped together. The most recent +window is first. Within each window, the tabs are returned +left-to-right." (with-js (let (windows) @@ -2966,9 +2908,10 @@ because it is special to the Javascript interpreter." (defvar js-read-tab-history nil) (defun js--read-tab (prompt) - "Read a Mozilla tab with prompt PROMPT. Return a cons of (TYPE . OBJECT). -TYPE is either 'window or 'tab, and OBJECT is a Javascript handle -to a ChromeWindow or a browser, respectively." + "Read a Mozilla tab with prompt PROMPT. +Return a cons of (TYPE . OBJECT). TYPE is either 'window or +'tab, and OBJECT is a Javascript handle to a ChromeWindow or a +browser, respectively." ;; Prime IDO (unless ido-mode @@ -3108,9 +3051,10 @@ to a ChromeWindow or a browser, respectively." (cons 'window (third selected-tab))))))) (defun js--guess-eval-defun-info (pstate) - "Internal helper for `js-eval-defun'. Returns a list (NAME . CLASSPARTS), -where CLASSPARTS is a list of strings making up the class name -and NAME is the name of the function part." + "Helper function for `js-eval-defun'. +Return a list (NAME . CLASSPARTS), where CLASSPARTS is a list of +strings making up the class name and NAME is the name of the +function part." (cond ((and (= (length pstate) 3) (eq (js--pitem-type (first pstate)) 'function) (= (length (js--pitem-name (first pstate))) 1) @@ -3129,9 +3073,9 @@ and NAME is the name of the function part." (t (error "Function not a toplevel defun or class member")))) (defvar js--js-context nil - "The current JS context. This is a cons like the one returned -from `js--read-tab'. Change with -`js-set-js-context'.") + "The current JavaScript context. +This is a cons like the one returned from `js--read-tab'. +Change with `js-set-js-context'.") (defconst js--js-inserter "(function(func_info,func) { @@ -3157,15 +3101,14 @@ from `js--read-tab'. Change with })") (defun js-set-js-context (context) - "Set the Javascript context to CONTEXT, reading from the user -if interactive" + "Set the JavaScript context to CONTEXT. +When called interactively, prompt for CONTEXT." (interactive (list (js--read-tab "Javascript Context: "))) (setq js--js-context context)) (defun js--get-js-context () - "Return a valid JS context. If one hasn't been set, or if it's -stale, ask the user for a new one." - + "Return a valid JavaScript context. +If one hasn't been set, or if it's stale, prompt for a new one." (with-js (when (or (null js--js-context) (js--js-handle-expired-p (cdr js--js-context)) @@ -3174,7 +3117,6 @@ stale, ask the user for a new one." (browser (not (js? (js< (cdr js--js-context) "contentDocument")))))) (setq js--js-context (js--read-tab "Javascript Context: "))) - js--js-context)) (defun js--js-content-window (context) @@ -3202,8 +3144,7 @@ stale, ask the user for a new one." (js! (res-prot "setSubstitution") alias path-uri)))) (defun* js-eval-defun () - "Update some Mozilla tab with defun containing point or after -point" + "Update a Mozilla tab using the JavaScript defun at point." (interactive) ;; This function works by generating a temporary file that contains @@ -3218,10 +3159,10 @@ point" (save-excursion (let (begin end pstate defun-info temp-name defun-body) - (js--end-of-defun) + (js-end-of-defun) (setq end (point)) (js--ensure-cache) - (js--beginning-of-defun) + (js-beginning-of-defun) (re-search-forward "\\_") (setq begin (match-beginning 0)) (setq pstate (js--forward-pstate)) @@ -3305,7 +3246,7 @@ point" ;;;###autoload (define-derived-mode js-mode nil "js" - "Major mode for editing JavaScript source text. + "Major mode for editing JavaScript. Key bindings: @@ -3316,16 +3257,16 @@ Key bindings: (set (make-local-variable 'indent-line-function) 'js-indent-line) (set (make-local-variable 'beginning-of-defun-function) - 'js--beginning-of-defun) + 'js-beginning-of-defun) (set (make-local-variable 'end-of-defun-function) - 'js--end-of-defun) + 'js-end-of-defun) (set (make-local-variable 'open-paren-in-column-0-is-defun-start) nil) (set (make-local-variable 'font-lock-defaults) (list js--font-lock-keywords nil nil nil nil '(font-lock-syntactic-keywords - . js--font-lock-syntactic-keywords))) + . js-font-lock-syntactic-keywords))) (set (make-local-variable 'parse-sexp-ignore-comments) t) (set (make-local-variable 'parse-sexp-lookup-properties) t) -- 2.39.2