Skip to content

Commit

Permalink
Merge pull request rust-lang#284 from riscy/master
Browse files Browse the repository at this point in the history 
adjust docstring formatting
  • Loading branch information
@nikomatsakis
nikomatsakis authored Oct 8, 2018
2 parents ee262cc + 5d0406f commit 12cb169
Showing 1 changed file with 45 additions and 48 deletions.
93 changes: 45 additions & 48 deletions rust-mode.el
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,13 +55,14 @@
"\\_>"))

(defun rust-looking-back-str (str)
"Like `looking-back' but for fixed strings rather than regexps (so that it's not so slow)"
"Return non-nil if there's a match on the text before point and STR.
Like `looking-back' but for fixed strings rather than regexps (so that it's not so slow)."
(let ((len (length str)))
(and (> (point) len)
(equal str (buffer-substring-no-properties (- (point) len) (point))))))

(defun rust-looking-back-symbols (SYMS)
"Return non-nil if the point is just after a complete symbol that is a member of the list of strings SYMS"
"Return non-nil if the point is just after a complete symbol that is a member of the list of strings SYMS."
(save-excursion
(let* ((pt-orig (point))
(beg-of-symbol (progn (forward-thing 'symbol -1) (point)))
Expand All @@ -71,7 +72,7 @@
(member (buffer-substring-no-properties beg-of-symbol pt-orig) SYMS)))))

(defun rust-looking-back-ident ()
"Non-nil if we are looking backwards at a valid rust identifier"
"Non-nil if we are looking backwards at a valid rust identifier."
(let ((beg-of-symbol (save-excursion (forward-thing 'symbol -1) (point))))
(looking-back rust-re-ident beg-of-symbol)))

Expand Down Expand Up @@ -116,30 +117,29 @@
:safe #'integerp)

(defcustom rust-indent-method-chain nil
"Indent Rust method chains, aligned by the '.' operators"
"Indent Rust method chains, aligned by the `.' operators."
:type 'boolean
:group 'rust-mode
:safe #'booleanp)

(defcustom rust-indent-where-clause nil
"Indent the line starting with the where keyword following a
function or trait. When nil, where will be aligned with fn or trait."
"Indent lines starting with the `where' keyword following a function or trait.
When nil, `where' will be aligned with `fn' or `trait'."
:type 'boolean
:group 'rust-mode
:safe #'booleanp)

(defcustom rust-playpen-url-format "https://play.rust-lang.org/?code=%s"
"Format string to use when submitting code to the playpen"
"Format string to use when submitting code to the playpen."
:type 'string
:group 'rust-mode)
(defcustom rust-shortener-url-format "https://is.gd/create.php?format=simple&url=%s"
"Format string to use for creating the shortened link of a playpen submission"
"Format string to use for creating the shortened link of a playpen submission."
:type 'string
:group 'rust-mode)

(defcustom rust-match-angle-brackets t
"Enable angle bracket matching. Attempt to match `<' and `>' where
appropriate."
"Whether to attempt angle bracket matching (`<' and `>') where appropriate."
:type 'boolean
:safe #'booleanp
:group 'rust-mode)
Expand All @@ -161,8 +161,7 @@ function or trait. When nil, where will be aligned with fn or trait."
:group 'rust-mode)

(defcustom rust-always-locate-project-on-open nil
"Whether to run `cargo locate-project' every time `rust-mode'
is activated."
"Whether to run `cargo locate-project' every time `rust-mode' is activated."
:type 'boolean
:group 'rust-mode)

Expand Down Expand Up @@ -351,7 +350,7 @@ buffer."
(rust-rewind-to-beginning-of-current-level-expr)
(+ (current-column) rust-indent-offset))))))
(cond
;; Indent inside a non-raw string only if the the previous line
;; Indent inside a non-raw string only if the previous line
;; ends with a backslash that is inside the same string
((nth 3 (syntax-ppss))
(let*
Expand Down Expand Up @@ -576,8 +575,9 @@ buffer."


(defun rust-path-font-lock-matcher (re-ident)
"Matches names like \"foo::\" or \"Foo::\" (depending on RE-IDENT, which should match
the desired identifiers), but does not match type annotations \"foo::<\"."
"Match occurrences of RE-IDENT followed by a double-colon.
Examples include to match names like \"foo::\" or \"Foo::\".
Does not match type annotations of the form \"foo::<\"."
`(lambda (limit)
(catch 'rust-path-font-lock-matcher
(while t
Expand All @@ -593,8 +593,7 @@ the desired identifiers), but does not match type annotations \"foo::<\"."
(throw 'rust-path-font-lock-matcher match))))))))

(defun rust-next-string-interpolation (limit)
"Search forward from point for next Rust interpolation marker
before LIMIT.
"Search forward from point for the next Rust interpolation marker before LIMIT.
Set point to the end of the occurrence found, and return match beginning
and end."
(catch 'match
Expand All @@ -615,8 +614,8 @@ and end."
(throw 'match (list start (point)))))))))))

(defun rust-string-interpolation-matcher (limit)
"Match next Rust interpolation marker before LIMIT and set
match data if found. Returns nil if not within a Rust string."
"Match the next Rust interpolation marker before LIMIT; set match data if found.
Returns nil if the point is not within a Rust string."
(when (rust-in-str)
(let ((match (rust-next-string-interpolation limit)))
(when match
Expand All @@ -630,7 +629,7 @@ match data if found. Returns nil if not within a Rust string."
"format"
"print"
"println")
"List of builtin Rust macros for string formatting used by `rust-mode-font-lock-keywords'. (`write!' is handled separately.)")
"List of builtin Rust macros for string formatting used by `rust-mode-font-lock-keywords' (`write!' is handled separately).")

(defvar rust-formatting-macro-opening-re
"[[:space:]\n]*[({[][[:space:]\n]*"
Expand Down Expand Up @@ -751,10 +750,11 @@ match data if found. Returns nil if not within a Rust string."
(goto-char dest))))))

(defun rust-rewind-to-decl-name ()
"If we are before an ident that is part of a declaration that
can have a where clause, rewind back to just before the name of
the subject of that where clause and return the new point.
Otherwise return nil"
"Return the point at the beginning of the name in a declaration.
I.e. if we are before an ident that is part of a declaration that
can have a where clause, rewind back to just before the name of
the subject of that where clause and return the new point.
Otherwise return nil."

(let* ((ident-pos (point))
(newpos (save-excursion
Expand Down Expand Up @@ -783,13 +783,13 @@ match data if found. Returns nil if not within a Rust string."

(defun rust-is-in-expression-context (token)
"Return t if what comes right after the point is part of an
expression (as opposed to starting a type) by looking at what
comes before. Takes a symbol that roughly indicates what is
after the point.
expression (as opposed to starting a type) by looking at what
comes before. Takes a symbol that roughly indicates what is
after the point.
This function is used as part of `rust-is-lt-char-operator' as
part of angle bracket matching, and is not intended to be used
outside of this context."
This function is used as part of `rust-is-lt-char-operator' as
part of angle bracket matching, and is not intended to be used
outside of this context."

(save-excursion
(let ((postchar (char-after)))
Expand Down Expand Up @@ -970,8 +970,8 @@ match data if found. Returns nil if not within a Rust string."
))))

(defun rust-is-lt-char-operator ()
"Return t if the < sign just after point is an operator rather
than an opening angle bracket, otherwise nil."
"Return t if the `<' after the point is the less-than operator.
Otherwise, for instance if it's an opening angle bracket, return nil."

(let ((case-fold-search nil))
(save-excursion
Expand Down Expand Up @@ -1019,9 +1019,8 @@ match data if found. Returns nil if not within a Rust string."
))))

(defun rust-electric-pair-inhibit-predicate-wrap (char)
"Wraps the default `electric-pair-inhibit-predicate' to prevent
inserting a \"matching\" > after a < that would be treated as a
less than sign rather than as an opening angle bracket."
"Prevent \"matching\" with a `>' when CHAR is the less-than operator.
This wraps the default defined by `electric-pair-inhibit-predicate'."
(or
(when (= ?< char)
(save-excursion
Expand Down Expand Up @@ -1067,7 +1066,7 @@ should be considered a paired angle bracket."
(not (looking-at "<"))))))))

(defun rust-mode-syntactic-face-function (state)
"Syntactic face function to distinguish doc comments from other comments."
"Return face which distinguishes doc and normal comments in the given syntax STATE."
(if (nth 3 state) 'font-lock-string-face
(save-excursion
(goto-char (nth 8 state))
Expand Down Expand Up @@ -1097,7 +1096,7 @@ should be considered a paired angle bracket."
If point is already in a raw string, this will apply the
appropriate string syntax to the character up to the end of the
raw string, or to `end', whichever comes first."
raw string, or to END, whichever comes first."
(let ((str-start (nth 8 (syntax-ppss))))
(when str-start
(when (save-excursion
Expand All @@ -1115,7 +1114,7 @@ raw string, or to `end', whichever comes first."
(goto-char (match-end 0))))))))

(defun rust-syntax-propertize (start end)
"A `syntax-propertize-function' for `rust-mode'."
"A `syntax-propertize-function' to apply properties from START to END."
(goto-char start)
(rust--syntax-propertize-raw-string end)
(funcall
Expand All @@ -1139,7 +1138,7 @@ raw string, or to `end', whichever comes first."
(point) end))

(defun rust-fill-prefix-for-comment-start (line-start)
"Determine what to use for `fill-prefix' based on what is at the beginning of a line."
"Determine what to use for `fill-prefix' based on the text at LINE-START."
(let ((result
;; Replace /* with same number of spaces
(replace-regexp-in-string
Expand Down Expand Up @@ -1304,7 +1303,7 @@ which calls this, does that afterwards."
With argument, do it that many times.
Negative argument -N means move back to Nth preceding end of defun.
Assume that this is called after beginning-of-defun. So point is
Assume that this is called after `beginning-of-defun'. So point is
at the beginning of the defun body.
This is written mainly to be used as `end-of-defun-function' for Rust."
Expand Down Expand Up @@ -1612,10 +1611,10 @@ See `compilation-error-regexp-alist' for help on their format.")

(defun rustc-scroll-down-after-next-error ()
"In the new style error messages, the regular expression
matches on the file name (which appears after `-->`), but the
start of the error appears a few lines earlier. This hook runs
after `M-x next-error`; it simply scrolls down a few lines in
the compilation window until the top of the error is visible."
matches on the file name (which appears after `-->`), but the
start of the error appears a few lines earlier. This hook runs
after `next-error' (\\[next-error]); it simply scrolls down a few lines in
the compilation window until the top of the error is visible."
(save-selected-window
(when (eq major-mode 'rust-mode)
(select-window (get-buffer-window next-error-last-buffer 'visible))
Expand Down Expand Up @@ -1646,8 +1645,7 @@ See `compilation-error-regexp-alist' for help on their format.")
;;; Functions to submit (parts of) buffers to the rust playpen, for
;;; sharing.
(defun rust-playpen-region (begin end)
"Create a sharable URL for the contents of the current region
on the Rust playpen."
"Create a shareable URL for the region from BEGIN to END on the Rust playpen."
(interactive "r")
(let* ((data (buffer-substring begin end))
(escaped-data (url-hexify-string data))
Expand All @@ -1672,8 +1670,7 @@ See `compilation-error-regexp-alist' for help on their format.")
(message "%s" last-line)))))))))

(defun rust-playpen-buffer ()
"Create a sharable URL for the contents of the current buffer
on the Rust playpen."
"Create a shareable URL for the contents of the buffer on the Rust playpen."
(interactive)
(rust-playpen-region (point-min) (point-max)))

Expand Down

0 comments on commit 12cb169

Please sign in to comment.