branch: elpa/swift-mode
commit ea77cf9157ed2a2bbf6874b6fbd15c2ca776f775
Author: taku0 <mxxouy6x3m_git...@tatapa.org>
Commit: taku0 <mxxouy6x3m_git...@tatapa.org>
Add comments
---
swift-mode-beginning-of-defun.el | 17 +++++++++++++++--
swift-mode-indent.el | 33 ++++++++++++++++++++++++++-------
swift-mode-lexer.el | 23 ++++++++++++++++-------
swift-mode.el | 3 +++
4 files changed, 60 insertions(+), 16 deletions(-)
diff --git a/swift-mode-beginning-of-defun.el b/swift-mode-beginning-of-defun.el
index 10a63db..8465cd4 100644
--- a/swift-mode-beginning-of-defun.el
+++ b/swift-mode-beginning-of-defun.el
@@ -33,7 +33,9 @@
(require 'swift-mode-indent)
(defun swift-mode:beginning-of-defun (&optional arg)
- "Move backward to the beginning of a defun."
+ "Move backward to the beginning of a defun.
+
+See `beginning-of-defun' for ARG."
(interactive)
(setq arg (or arg 1))
(let (result
@@ -88,6 +90,9 @@
result))
(defun swift-mode:beginning-of-defun-1 (next-token-function)
+ "Goto the beginning of a defun.
+
+NEXT-TOKEN-FUNCTION skips the preceding/following token."
(catch 'swift-mode:found-defun
(while (not (eq (swift-mode:token:type (funcall next-token-function))
'outside-of-buffer))
@@ -98,6 +103,9 @@
(defun swift-mode:is-point-before-body-of-defun ()
+ "Return t it the point is just before the body of a defun.
+
+Return nil otherwise."
(and
(eq (char-after) ?{)
(progn
@@ -154,7 +162,9 @@ Intended for internal use."
(swift-mode:skip-whitespaces))))
(defun swift-mode:end-of-defun (&optional arg)
- "Move forward to the end of a defun."
+ "Move forward to the end of a defun.
+
+See `end-of-defun' for ARG."
(interactive)
(setq arg (or arg 1))
(let (result)
@@ -173,6 +183,9 @@ Intended for internal use."
result))
(defun swift-mode:end-of-defun-1 (next-token-function)
+ "Goto the end of a defun.
+
+NEXT-TOKEN-FUNCTION skips the preceding/following token."
(catch 'swift-mode:found-defun
(while (not (eq (swift-mode:token:type (funcall next-token-function))
'outside-of-buffer))
diff --git a/swift-mode-indent.el b/swift-mode-indent.el
index a821519..63b2996 100644
--- a/swift-mode-indent.el
+++ b/swift-mode-indent.el
@@ -93,6 +93,7 @@
"Parent tokens for expressions.")
(defun swift-mode:indent-line ()
+ "Indent the current line."
(let ((indent (save-excursion (swift-mode:calculate-indent)))
(current-indent
(save-excursion (back-to-indentation) (current-column))))
@@ -103,6 +104,7 @@
(save-excursion (indent-line-to indent)))))
(defun swift-mode:calculate-indent ()
+ "Return the indentation of the current line."
(back-to-indentation)
(if (nth 4 (syntax-ppss))
@@ -115,6 +117,7 @@
(swift-mode:calculate-indent-of-code)))
(defun swift-mode:calculate-indent-of-multiline-comment ()
+ "Return the indentation of the current line inside a multiline comment."
(back-to-indentation)
(let ((comment-beginning-position (nth 8 (syntax-ppss))))
(forward-line -1)
@@ -134,6 +137,7 @@
(current-column)))))
(defun swift-mode:calculate-indent-of-code ()
+ "Return the indentation of the current line outside multiline comments."
(back-to-indentation)
(let* ((previous-token (save-excursion (swift-mode:backward-token)))
(previous-type (swift-mode:token:type previous-token))
@@ -591,8 +595,7 @@ If scanning stops at eol, align with the next token with
BOL-OFFSET.
If AFTER-ATTRIBUTES is nil, skip lines with only attributes at the start of
the expression."
(save-excursion
- (let* ((pos (point))
- (parent-of-previous-line
+ (let* ((parent-of-previous-line
(save-excursion
(swift-mode:goto-non-comment-bol-with-same-nesting-level)
(swift-mode:backward-token)))
@@ -1069,12 +1072,12 @@ with one of those token types.
STOP-AT-EOL-TOKEN-TYPES is a list of token types that if we skipped the end of
a line just after a token with one of given toke typen, the function returns.
Typically, this is a list of token types that separates list elements
-\(e.g. ',', ';'). If STOP-AT-EOL-TOKEN-TYPES is the symbol `any', it matches
+\(e.g. ',', ';'). If STOP-AT-EOL-TOKEN-TYPES is the symbol `any', it matches
all tokens.
STOP-AT-BOL-TOKEN-TYPES is a list of token types that if we hit
the beginning of a line just before a token with one of given token types,
-the function returns. Typically, this is a list of token types that starts
-list element (e.g. 'case' of switch statement body). If STOP-AT-BOL-TOKEN-TYPES
+the function returns. Typically, this is a list of token types that starts
+list element (e.g. 'case' of switch statement body). If
STOP-AT-BOL-TOKEN-TYPES
is the symbol `any', it matches all tokens."
(let*
((parent (swift-mode:backward-token-or-list))
@@ -1128,6 +1131,7 @@ is the symbol `any', it matches all tokens."
parent))
(defun swift-mode:align-with-next-token (parent &optional offset)
+ "Return indentation with the PARENT and OFFSET."
(let ((parent-end (swift-mode:token:end parent)))
(goto-char parent-end)
(forward-comment (point-max))
@@ -1138,6 +1142,7 @@ is the symbol `any', it matches all tokens."
(+ (or offset 0) (current-column))))
(defun swift-mode:align-with-current-line (&optional offset)
+ "Return indentation of the current line with OFFSET."
(swift-mode:goto-non-comment-bol)
(swift-mode:skip-whitespaces)
(+ (or offset 0) (current-column)))
@@ -1275,6 +1280,11 @@ It is a Generic parameter list if:
(defun swift-mode:try-skip-generic-parameters
(skip-token-or-list-function matching-bracket-text unmatching-bracket-text)
+ "Skip generic parameters if the point is just before/after one.
+
+SKIP-TOKEN-OR-LIST-FUNCTION skips forward/backward a token or a list.
+MATCHING-BRACKET-TEXT is a text of the matching bracket.
+UNMATCHING-BRACKET-TEXT is a text of the current bracket."
(let ((pos (point))
(prohibited-tokens (append
unmatching-bracket-text
@@ -1356,6 +1366,9 @@ Return nil otherwise."
(skip-syntax-forward " >"))
(defun swift-mode:incomplete-comment-p ()
+ "Return t if the point is inside an incomplete comment.
+
+Return nil otherwise."
(and (nth 4 (syntax-ppss))
(save-excursion
(goto-char (nth 8 (syntax-ppss)))
@@ -1364,9 +1377,10 @@ Return nil otherwise."
(defun swift-mode:indent-new-comment-line (&optional soft)
"Break the line at the point and indent the new line.
-If the point is inside a comment, continue the comment. If the comment is a
+If the point is inside a comment, continue the comment. If the comment is a
multiline comment, close the previous comment and start new one if
-`comment-multi-line' is nil."
+`comment-multi-line' is nil.
+See `indent-new-comment-line' for SOFT."
(interactive)
(let* ((parser-state (syntax-ppss))
(is-inside-comment (nth 4 parser-state))
@@ -1422,6 +1436,9 @@ multiline comment, close the previous comment and start
new one if
(indent-according-to-mode)))))
(defun swift-mode:post-self-insert ()
+ "Miscellaneous logic for electric indentation."
+ ;; Indents electrically and insert a space when "*" is inserted at the
+ ;; beginning of a line inside a multiline comment.
(cond
((and
(= last-command-event ?*)
@@ -1430,6 +1447,8 @@ multiline comment, close the previous comment and start
new one if
(when swift-mode:insert-space-after-asterisk-in-comment
(insert-before-markers-and-inherit " "))
(indent-according-to-mode))
+
+ ;; Fixes "* /" at the end of a multiline comment to "*/".
((and
(= last-command-event ?/)
swift-mode:fix-comment-close
diff --git a/swift-mode-lexer.el b/swift-mode-lexer.el
index ee8fccb..97cabb7 100644
--- a/swift-mode-lexer.el
+++ b/swift-mode-lexer.el
@@ -46,7 +46,12 @@
stop-at-bol-token-types))
(defun swift-mode:token (type text start end)
- "Construct and returns a token."
+ "Construct and return a token.
+
+TYPE is the type of the token such as `inix-operator' or {.
+TEXT is the text of the token.
+START is the start position of the token.
+END is the point after the token."
(list type text start end))
(defun swift-mode:token:type (token)
@@ -448,7 +453,9 @@ That is supertype declaration or type declaration of let or
var."
'{)))
(defun swift-mode:fix-operator-type (token)
- "Return new operator token with proper token type."
+ "Return new operator token with proper token type.
+
+Other properties are the same as the TOKEN."
;; Operator type (i.e. prefix, postfix, infix) is decided from spaces or
;; comments around the operator.
;;
https://developer.apple.com/library/ios/documentation/Swift/Conceptual/Swift_Programming_Language/LexicalStructure.html#//apple_ref/doc/uid/TP40014097-CH30-ID410
@@ -491,7 +498,7 @@ That is supertype declaration or type declaration of let or
var."
(swift-mode:token type text start end)))
(defun swift-mode:backquote-identifier-if-after-dot (token)
- "Backquote identifiers including keywords if it is after dot.
+ "Backquote identifier TOKEN, including keywords, if it is after a dot.
See SE-0071:
https://github.com/apple/swift-evolution/blob/master/proposals/0071-member-keywords.md";
@@ -561,8 +568,9 @@ type `out-of-buffer'"
token)))))
(defun swift-mode:forward-token-simple ()
- "Like `swift-mode:forward-token' without recursion, and never produces
-`implicit-;' or `type-:'."
+ "Like `swift-mode:forward-token' without recursion.
+
+This function does not return `implicit-;' or `type-:'."
(forward-comment (point-max))
(cond
;; Outside of buffer
@@ -748,8 +756,9 @@ type `out-of-buffer'."
token)))))
(defun swift-mode:backward-token-simple ()
- "Like `swift-mode:backward-token' without recursion, and never produces
-`implicit-;' or `type-:'."
+ "Like `swift-mode:backward-token' without recursion.
+
+This function does not return `implicit-;' or `type-:'."
(forward-comment (- (point)))
(cond
;; Outside of buffer
diff --git a/swift-mode.el b/swift-mode.el
index 21278f9..f040db8 100644
--- a/swift-mode.el
+++ b/swift-mode.el
@@ -70,6 +70,9 @@
;;; `foward-sexp-function'
(defun swift-mode:forward-sexp (&optional arg)
+ "Move forward/backward a token or list.
+
+See `forward-sexp for ARG."
(setq arg (or arg 1))
(if (< 0 arg)
(while (< 0 arg)
