[nongnu] elpa/swift-mode 3751335 398/496: Tweak and checkdoc compliance

[ELPA Syncer]

branch: elpa/swift-mode
commit 3751335c3d053f2072d202c27e12e9909f11de91
Author: taku0 <mxxouy6x3m_github@tatapa.org>
Commit: taku0 <mxxouy6x3m_github@tatapa.org>

    Tweak and checkdoc compliance
---
 swift-mode-repl.el | 145 +++++++++++++++++++++++++++++++++++------------------
 1 file changed, 96 insertions(+), 49 deletions(-)

diff --git a/swift-mode-repl.el b/swift-mode-repl.el
index c64abae..e8acdde 100644
--- a/swift-mode-repl.el
+++ b/swift-mode-repl.el
@@ -109,6 +109,7 @@ The string is splitted by spaces, then unquoted."
 
 (defvar swift-mode:repl-command-queue nil
   "List of strings to be executed on REPL prompts.
+
 Use `swift-mode:enqueue-repl-commands' to enqueue commands.
 If an element is a cons cell, its car is used as a regexp for prompt and
 cdr is used as a command.  If its car is a function, it is called to search
@@ -123,28 +124,31 @@ otherwise.")
 
 (defun swift-mode:command-list-to-string (cmd)
   "Concatenate the CMD unless it is a string.
+
 This function quotes elements appropriately."
   (if (stringp cmd) cmd (combine-and-quote-strings cmd)))
 
 (defun swift-mode:command-string-to-list (cmd)
   "Split the CMD unless it is a list.
+
 This function respects quotes."
   (if (listp cmd) cmd (split-string-and-unquote cmd)))
 
 ;;;###autoload
 (defun swift-mode:run-repl (cmd &optional dont-switch keep-default)
   "Run a Swift REPL process.
+
 This function input and output via buffer `*CMD*' where CMD is replaced with
 the CMD given.
-If there is a process already running in `*CMD*', switch to that buffer.
-CMD is a string or a list, interpreted as a command line. The default value is
-`swift-mode:repl-executable'. This function updates the buffer local variable
-`swift-mode:repl-executable' with the given CMD unless KEEP-DEFAULT is non-nil,
+If there is a process already running in `*CMD*', and DONT-SWITCH is nil,
+switch to that buffer.
+CMD is a string or a list, interpreted as a command line.  The default value is
+`swift-mode:repl-executable'.  This function updates the buffer local variable
+`swift-mode:repl-executable' with the given CMD if KEEP-DEFAULT is nil,
 so it will be used as the default value for the next invocatoin in the current
 buffer.
-If DONT-SWITCH is non-nil, cursor will stay in current buffer.
 If KEEP-DEFAULT is non-nil, the `swift-mode:repl-executable' and the global
-variable `swift-mode:repl-buffer' are not updated. The buffer local variable
+variable `swift-mode:repl-buffer' are not updated.  The buffer local variable
 `swift-mode:repl-buffer' is always updated.
 Runs the hook `swift-repl-mode-hook' \(after the `comint-mode-hook' is run).
 \(Type \\[describe-mode] in the process buffer for a list of commands.)"
@@ -180,6 +184,7 @@ Runs the hook `swift-repl-mode-hook' \(after the 
`comint-mode-hook' is run).
 ;;;###autoload
 (defun swift-mode:send-region (start end)
   "Send the current region to the inferior swift process.
+
 START and END define region within current buffer"
   (interactive "r")
   (swift-mode:run-repl swift-mode:repl-executable t t)
@@ -197,15 +202,16 @@ START and END define region within current buffer"
 
 A REPL can be fired up with M-x swift-mode:run-repl or M-x run-swift.
 
-Customization: Entry to this mode runs the hooks on comint-mode-hook and
-swift-repl-mode-hook (in that order).
+Customization: Entry to this mode runs the hooks on `comint-mode-hook' and
+`swift-repl-mode-hook' (in that order).
 
 You can send text to the REPL process from other buffers containing source.
-    swift-mode:send-region sends the current region to the REPL process,
-    swift-mode:send-buffer sends the current buffer to the REPL process.")
+`swift-mode:send-region' sends the current region to the REPL process,
+`swift-mode:send-buffer' sends the current buffer to the REPL process.")
 
 (defun swift-mode:call-process (executable &rest args)
   "Call EXECUTABLE synchronously in separate process.
+
 EXECUTABLE may be a string or a list.  The string is splitted by spaces,
 then unquoted.
 ARGS are rest arguments, appended to the argument list.
@@ -214,6 +220,7 @@ Returns the exit status."
 
 (defun swift-mode:call-process-async (executable &rest args)
   "Call EXECUTABLE asynchronously in separate process.
+
 EXECUTABLE may be a string or a list.  The string is splitted by spaces,
 then unquoted.
 ARGS are rest arguments, appended to the argument list."
@@ -221,6 +228,7 @@ ARGS are rest arguments, appended to the argument list."
 
 (defun swift-mode:do-call-process (executable infile destination display args)
   "Wrapper for `call-process'.
+
 EXECUTABLE may be a string or a list.  The string is splitted by spaces,
 then unquoted.
 For INFILE, DESTINATION, DISPLAY, see `call-process'.
@@ -236,6 +244,7 @@ Returns the exit status."
 
 (defun swift-mode:call-process-to-json (executable &rest args)
   "Call EXECUTABLE synchronously in separate process.
+
 The output is parsed as a JSON document.
 EXECUTABLE may be a string or a list.  The string is splitted by spaces,
 then unquoted.
@@ -255,6 +264,7 @@ ARGS are rest arguments, appended to the argument list."
 
 (defun swift-mode:describe-package (project-directory)
   "Read the package definition from the manifest file Package.swift.
+
 The manifest file is searched from the PROJECT-DIRECTORY, defaults to
 `default-directory', or its ancestors.
 Return a JSON object."
@@ -265,6 +275,7 @@ Return a JSON object."
 
 (defun swift-mode:read-main-module (project-directory)
   "Read the main module description from the manifest file Package.swift.
+
 The manifest file is searched from the PROJECT-DIRECTORY, defaults to
 `default-directory', or its ancestors."
   (let* ((description (swift-mode:describe-package project-directory))
@@ -275,24 +286,27 @@ The manifest file is searched from the PROJECT-DIRECTORY, 
defaults to
 
 (defun swift-mode:read-package-name (project-directory)
   "Read the package name from the manifest file Package.swift.
+
 The manifest file is searched from the PROJECT-DIRECTORY, defaults to
 `default-directory', or its ancestors."
   (cdr (assoc 'name (swift-mode:read-main-module project-directory))))
 
 (defun swift-mode:read-c99-name (project-directory)
   "Read the C99 name from the manifest file Package.swift.
+
 The manifest file is searched from the PROJECT-DIRECTORY, defaults to
 `default-directory', or its ancestors."
   (cdr (assoc 'c99name (swift-mode:read-main-module project-directory))))
 
 (defun swift-mode:read-module-type (project-directory)
   "Read the module type from the manifest file Package.swift.
+
 The manifest file is searched from the PROJECT-DIRECTORY, defaults to
 `default-directory', or its ancestors."
   (cdr (assoc 'type (swift-mode:read-main-module project-directory))))
 
 (defun swift-mode:join-path (directory &rest components)
-  "Append each path components in COMPONENTS after DIRECTORY."
+  "Make path string for DIRECTORY followed by COMPONENTS."
   (seq-reduce
    (lambda (directory component) (expand-file-name component directory))
    components
@@ -302,6 +316,7 @@ The manifest file is searched from the PROJECT-DIRECTORY, 
defaults to
                                                    &optional
                                                    directory)
   "Find the nearest ancestor-or-self directory satisfying a PREDICATE.
+
 Traverse up from DIRECTORY up to the root directory.
 Return a directory satisfying the PREDICATE if exists.  Otherwise, return nil."
   (unless directory (setq directory default-directory))
@@ -318,6 +333,7 @@ Return a directory satisfying the PREDICATE if exists.  
Otherwise, return nil."
 
 (defun swift-mode:find-swift-project-directory (&optional directory)
   "Find a file Package.swift in the DIRECTORY or its ancestors.
+
 Return a directory path if found.  Return nil otherwise."
   (swift-mode:find-ancestor-or-self-directory
    'swift-mode:swift-project-directory-p directory))
@@ -328,6 +344,7 @@ Return a directory path if found.  Return nil otherwise."
 
 (defun swift-mode:ensure-swift-project-directory (project-directory)
   "Check PROJECT-DIRECTORY contains the manifest file Package.swift.
+
 If PROJECT-DIRECTORY is nil, this function searches it from `default-directory'
 or its ancestors."
   (unless project-directory
@@ -348,18 +365,21 @@ or its ancestors."
 
 (defun swift-mode:find-xcode-project-directory (&optional directory)
   "Find a file *.xcodeproj in the DIRECTORY or its ancestors.
+
 Return a directory path if found.  Return nil otherwise."
   (swift-mode:find-ancestor-or-self-directory
    'swift-mode:xcode-project-directory-p directory))
 
 (defun swift-mode:find-xcode-workspace-directory (&optional directory)
   "Find a file *.xcworkspace in the DIRECTORY or its ancestors.
+
 Return a directory path if found.  Return nil otherwise."
   (swift-mode:find-ancestor-or-self-directory
    'swift-mode:xcode-workspace-directory-p directory))
 
 (defun swift-mode:ensure-xcode-project-directory (project-directory)
   "Check PROJECT-DIRECTORY contains *.xcworkspace or *.xcodeproj.
+
 If PROJECT-DIRECTORY is nil, this function searches it from `default-directory'
 or its ancestors."
   (unless project-directory
@@ -403,10 +423,12 @@ or its ancestors."
     (widget-choose "Choose a device" items)))
 
 (defun swift-mode:read-xcode-build-settings (project-directory
-                                             scheme
-                                             device-identifier)
+                                             device-identifier
+                                             scheme)
   "Read Xcode build settings in PROJECT-DIRECTORY.
-DEVICE-IDENTIFIER is used as the destination parameter for xcodebuild."
+
+DEVICE-IDENTIFIER is used as the destination parameter for xcodebuild.
+SCHEME is the name of the project scheme in Xcode."
   (with-temp-buffer
     (let ((default-directory project-directory))
       (unless (zerop (swift-mode:call-process
@@ -425,7 +447,7 @@ DEVICE-IDENTIFIER is used as the destination parameter for 
xcodebuild."
       settings)))
 
 (defun swift-mode:xcodebuild-list (project-directory)
-  "Returns the contents of `xcodebuild -list' as JSON."
+  "Return the contents of `xcodebuild -list' in PROJECT-DIRECTORY as JSON."
   (let ((default-directory project-directory)
         (json-array-type 'list))
     (swift-mode:call-process-to-json
@@ -434,7 +456,9 @@ DEVICE-IDENTIFIER is used as the destination parameter for 
xcodebuild."
      "-json")))
 
 (defun swift-mode:read-project-scheme (project-directory)
-  "Reads and prompts for a project's scheme in the minibuffer."
+  "Read and prompt for a project's scheme in the minibuffer.
+
+xcodebuild is executed in PROJECT-DIRECTORY."
   (let* ((json (swift-mode:xcodebuild-list project-directory))
          (project (cdr (assoc 'project json)))
          (schemes (cdr (assoc 'schemes project)))
@@ -448,6 +472,7 @@ DEVICE-IDENTIFIER is used as the destination parameter for 
xcodebuild."
 
 (defun swift-mode:locate-xcode ()
   "Return the developer path in Xcode.app.
+
 Typically, it is /Applications/Xcode.app/Contents/Developer."
   (string-trim-right
    (with-output-to-string
@@ -461,6 +486,7 @@ Typically, it is 
/Applications/Xcode.app/Contents/Developer."
 ;;;###autoload
 (defun swift-mode:build-swift-module (&optional project-directory args)
   "Build a Swift module in the PROJECT-DIRECTORY.
+
 If PROJECT-DIRECTORY is nil or omited, it is searched from `default-directory'
 or its ancestors.
 An list ARGS are appended for builder command line arguments."
@@ -497,23 +523,27 @@ An list ARGS are appended for builder command line 
arguments."
 (defun swift-mode:build-ios-app (&optional project-directory
                                            device-identifier
                                            scheme)
-  "Build an iOS app in the PROJECT-DIRECTORY for the given SCHEME.
-Build it for iOS simulator device DEVICE-IDENTIFIER.
+  "Build an iOS app in the PROJECT-DIRECTORY.
+
+Build it for iOS simulator device DEVICE-IDENTIFIER for the given SCHEME.
 If PROJECT-DIRECTORY is nil or omitted, it is searched from `default-directory'
 or its ancestors.
-If DEVICE-IDENTIFIER is nil or omitted,
-the value of `swift-mode:ios-simulator-device-identifier' is used.
-If SCHEME is nil or omitted,
-the value of `swift-mode:ios-project-scheme' is used.
-"
+DEVICE-IDENTIFIER is the device identifier of the iOS simulator.  If it is nil
+or omitted, the value of `swift-mode:ios-simulator-device-identifier' is used.
+SCHEME is the name of the project scheme in Xcode.  If it is nil or omitted,
+the value of `swift-mode:ios-project-scheme' is used."
   (interactive
-   (list
-    (if current-prefix-arg
-        (swift-mode:read-project-directory)
-      (swift-mode:find-xcode-project-directory))
-    (if current-prefix-arg
-        (swift-mode:read-ios-simulator-device-identifier)
-      swift-mode:ios-simulator-device-identifier)))
+   (let ((project-directory (if current-prefix-arg
+                                (swift-mode:read-project-directory)
+                              (swift-mode:find-xcode-project-directory))))
+     (list
+      project-directory
+      (if current-prefix-arg
+          (swift-mode:read-ios-simulator-device-identifier)
+        swift-mode:ios-simulator-device-identifier)
+      (if current-prefix-arg
+          (swift-mode:read-project-scheme project-directory)
+        swift-mode:ios-project-scheme))))
   (setq project-directory
         (swift-mode:ensure-xcode-project-directory project-directory))
   (unless device-identifier
@@ -523,9 +553,10 @@ the value of `swift-mode:ios-project-scheme' is used.
            (swift-mode:read-ios-simulator-device-identifier))))
   (setq swift-mode:ios-simulator-device-identifier device-identifier)
   (unless scheme
-    (setq scheme (or
-                  swift-mode:ios-project-scheme
-                  (swift-mode:read-project-scheme project-directory))))
+    (setq scheme
+          (or
+           swift-mode:ios-project-scheme
+           (swift-mode:read-project-scheme project-directory))))
   (setq swift-mode:ios-project-scheme scheme)
 
   (with-current-buffer (get-buffer-create "*swift-mode:compilation*")
@@ -551,7 +582,9 @@ the value of `swift-mode:ios-project-scheme' is used.
 
 (defun swift-mode:wait-for-prompt-then-execute-commands (string)
   "Execute the next command from the queue if the point is on a prompt.
-Itended for used as a `comint-output-filter-functions'."
+
+Itended for used as a `comint-output-filter-functions'.
+STRING is passed to the command."
   (let ((command (car swift-mode:repl-command-queue)))
     (when (and
            ;; The point is on an input field of comint.
@@ -620,6 +653,7 @@ Itended for used as a `comint-output-filter-functions'."
 ;;;###autoload
 (defun swift-mode:debug-swift-module (&optional project-directory)
   "Run debugger on a Swift module in the PROJECT-DIRECTORY.
+
 If PROJECT-DIRECTORY is nil or omited, it is searched from `default-directory'
 or its ancestors."
   (interactive
@@ -635,6 +669,7 @@ or its ancestors."
 
 (defun swift-mode:find-ios-simulator-process ()
   "Return the process ID of an iOS simulator process if exists.
+
 Return nil otherwise."
   (with-temp-buffer
     (swift-mode:call-process "ps" "-x" "-o" "pid,comm")
@@ -673,6 +708,7 @@ Return nil otherwise."
 
 (defun swift-mode:install-ios-app (device-identifier codesigning-folder-path)
   "Install an iOS app to an iOS simulator with DEVICE-IDENTIFIER.
+
 CODESIGNING-FOLDER-PATH is the path of the app."
   (with-temp-buffer
     (unless (zerop (swift-mode:call-process
@@ -687,6 +723,7 @@ CODESIGNING-FOLDER-PATH is the path of the app."
                                   &optional
                                   wait-for-debugger)
   "Launch an iOS app in DEVICE-IDENTIFIER.
+
 PRODUCT-BUNDLE-IDENTIFIER is the product bundle identifier of the app.
 If WAIT-FOR-DEBUGGER is non-nil, the new process is suspended until a debugger
 attaches to it."
@@ -705,6 +742,7 @@ attaches to it."
 
 (defun swift-mode:search-process-stopped-message (process-identifier)
   "Find a message of process suspension in the comint output.
+
 PROCESS-IDENTIFIER is the process ID."
   (let ((expected-output
          (concat "Process "
@@ -717,19 +755,27 @@ PROCESS-IDENTIFIER is the process ID."
 (defun swift-mode:debug-ios-app (&optional project-directory
                                            device-identifier
                                            scheme)
-  "Run debugger on an iOS app in the PROJECT-DIRECTORY for the given SCHEME.
+  "Run debugger on an iOS app in the PROJECT-DIRECTORY.
+
+Run it for iOS simulator device DEVICE-IDENTIFIER for the given SCHEME.
 If PROJECT-DIRECTORY is nil or omitted, it is searched from `default-directory'
 or its ancestors.
-DEVICE-IDENTIFIER is the device identifier of the iOS simulator.
-SCHEME is the name of the project scheme in Xcode."
+DEVICE-IDENTIFIER is the device identifier of the iOS simulator.  If it is nil
+or omitted, the value of `swift-mode:ios-simulator-device-identifier' is used.
+SCHEME is the name of the project scheme in Xcode.  If it is nil or omitted,
+the value of `swift-mode:ios-project-scheme' is used."
   (interactive
-   (list
-    (if current-prefix-arg
-        (swift-mode:read-project-directory)
-      (swift-mode:find-xcode-project-directory))
-    (if current-prefix-arg
-        (swift-mode:read-ios-simulator-device-identifier)
-      swift-mode:ios-simulator-device-identifier)))
+   (let ((project-directory (if current-prefix-arg
+                                (swift-mode:read-project-directory)
+                              (swift-mode:find-xcode-project-directory))))
+     (list
+      project-directory
+      (if current-prefix-arg
+          (swift-mode:read-ios-simulator-device-identifier)
+        swift-mode:ios-simulator-device-identifier)
+      (if current-prefix-arg
+          (swift-mode:read-project-scheme project-directory)
+        swift-mode:ios-project-scheme))))
   (setq project-directory
         (swift-mode:ensure-xcode-project-directory project-directory))
   (unless device-identifier
@@ -739,15 +785,16 @@ SCHEME is the name of the project scheme in Xcode."
            (swift-mode:read-ios-simulator-device-identifier))))
   (setq swift-mode:ios-simulator-device-identifier device-identifier)
   (unless scheme
-    (setq scheme (or
-                  swift-mode:ios-project-scheme
-                  (swift-mode:read-project-scheme project-directory))))
+    (setq scheme
+          (or
+           swift-mode:ios-project-scheme
+           (swift-mode:read-project-scheme project-directory))))
   (setq swift-mode:ios-project-scheme scheme)
   (let* ((build-settings
           (swift-mode:read-xcode-build-settings
            project-directory
-           scheme
-           device-identifier))
+           device-identifier
+           scheme))
          (codesigning-folder-path
           (cdr (assoc "CODESIGNING_FOLDER_PATH" build-settings)))
          (product-bundle-identifier