Merge branch 'review-commands'

documents/README.org

@@ -410,6 +410,7 @@ When =slot-value= is the only parameter specified then:
   =error=).
 - Dummy variables are called =_=.
 - Prefer American spelling.
+- Construct =define-command= requires a short one-line docstring without newlines.
 
 # - Conversion functions =FROM->TO= or =->TO= for generic functions.  The
 #   only one that comes to mind is =url= which does not follow this convention...

source/auto-rules.lisp

@@ -303,10 +303,9 @@ Implies that the request is a top-level one."
     (setf (previous-url buffer) url)))
 
 (define-command-global save-non-default-modes-for-future-visits ()
-  "Save the modes present in `default-modes' and not present in current modes as
-:excluded, and modes that are present in mode list but not in `default-modes' as
-:included, to one of the auto-rules. Apply the resulting rule for all the future
-visits to this URL, inferring the matching condition with `url-infer-match'.
+  "Save the enabled non-default modes for future visits.
+
+The matching URL logic is dictacted by `url-infer-match'.
 
 This command does not save non-rememberable modes. If you want auto-rules to
 remember a particular mode, configure it to be `rememberable-p' in your
@@ -333,10 +332,9 @@ For the storage format see the comment in the header of your `auto-rules-file'."
                               :test #'mode=))))
 
 (define-command-global save-exact-modes-for-future-visits ()
-  "Store the exact list of enabled modes to auto-rules for all the future visits
-of this domain/host/URL/group of websites inferring the suitable matching
-condition by user input.
-Uses `url-infer-match', see its documentation for matching rules.
+  "Save the enabled modes for future visits.
+
+The matching URL logic is dictacted by `url-infer-match'.
 
 This command does not save non-rememberable modes. If you want auto-rules to
 save a particular mode, configure it to be `rememberable-p' in your

source/buffer.lisp

@@ -860,9 +860,9 @@ Return the created buffer."
                                        (id parent-buffer))))))
   buffer)
 
-(define-command update-document-model (&key (buffer (current-buffer)))
-  "Update BUFFER's `document-model' with the page source augmented with Nyxt
-identifiers."
+(export-always 'update-document-model)
+(defun update-document-model (&key (buffer (current-buffer)))
+  "Update BUFFER's `document-model' as to include Nyxt identifiers."
   (ps-eval :buffer buffer
     (defvar nyxt-identifier-counter 0)
     (defun add-nyxt-identifiers (node)
@@ -1334,8 +1334,8 @@ BUFFERS should be a list of `buffer's."
         (mapcar #'buffer-delete (buffer-list)))))
 
 (define-command delete-current-buffer (&optional (buffer (current-buffer)))
-  "Delete the current buffer, and make the next buffer the current one. If no
-other buffers exist, set the url of the current buffer to the start page."
+  "Delete the current buffer and switch to the last visited one.
+If no other buffers exist, load the start page."
   (buffer-delete buffer))
 
 (define-command delete-other-buffers (&optional (buffer (current-buffer)))

source/mode/document.lisp

@@ -430,8 +430,7 @@ The inner-text must not be modified, so that we can jump to the anchor of the sa
           :sources (make-instance 'heading-source :buffer buffer)))
 
 (define-command jump-to-heading-buffers ()
-  "Jump to a particular heading, of type h1, h2, h3, h4, h5, or h6 across a set
-of buffers."
+  "Jump to a heading (H1 to H6) among a set of buffers."
   (let ((buffers (prompt
                   :prompt "Select headings from buffers"
                   :sources (make-instance 'buffer-source

source/mode/hint.lisp

@@ -518,52 +518,45 @@ FUNCTION is the action to perform on the selected elements."
         (plump:tag-name element)))
 
 (define-command follow-hint ()
-  "Prompt for element hints and open them in the current buffer.
-Uses `%follow-hint' internally."
-  (let ((buffer (current-buffer)))
-    (query-hints "Interact with element"
-                 (lambda (results)
-                   (%follow-hint (first results))
-                   (mapcar (rcurry #'%follow-hint-new-buffer buffer)
-                           (rest results))))))
+  "Follow the top element hint selection in the current buffer."
+  (query-hints "Select elements"
+               (lambda (results)
+                 (%follow-hint (first results))
+                 (mapcar (rcurry #'%follow-hint-new-buffer (current-buffer))
+                         (rest results)))))
 
 (define-command follow-hint-new-buffer ()
-  "Like `follow-hint', but open the selected hints in new buffers (no focus).
-Uses `%follow-hint-new-buffer' internally."
-  (let ((buffer (current-buffer)))
-    (query-hints "Open element in new buffer"
-                 (lambda (result) (mapcar (rcurry #'%follow-hint-new-buffer buffer)
-                                     result)))))
+  "Like `follow-hint', but selection is handled in background buffers."
+  (query-hints "Select elements"
+               (lambda (result)
+                 (mapcar (rcurry #'%follow-hint-new-buffer (current-buffer))
+                         result))))
 
+;; Consider renaming to follow-hint-new-foreground-buffer.
 (define-command follow-hint-new-buffer-focus ()
-  "Like `follow-hint-new-buffer', but with focus.
-Uses `%follow-hint-new-buffer-focus' internally."
+  "Like `follow-hint-new-buffer', but switch to the top background buffer."
   (let ((buffer (current-buffer)))
-    (query-hints "Open element in new buffer"
+    (query-hints "Select elements"
                  (lambda (result)
                    (%follow-hint-new-buffer-focus (first result) buffer)
                    (mapcar (rcurry #'%follow-hint-new-buffer buffer)
                            (rest result))))))
 
 (define-command follow-hint-nosave-buffer ()
-  "Like `follow-hint', but open the selected hints in new `nosave-buffer's (no
-focus).
-Uses `%follow-hint-nosave-buffer' internally."
-  (query-hints "Open element in new buffer"
+  "Like `follow-hint-new-buffer', but use `nosave-buffer's."
+  (query-hints "Select elements"
                (lambda (result) (mapcar #'%follow-hint-nosave-buffer result))))
 
 (define-command follow-hint-nosave-buffer-focus ()
-  "Like `follow-hint-nosave-buffer', but with focus.
-Uses `%follow-hint-nosave-buffer-focus' internally."
-  (query-hints "Open element in new buffer"
+  "Like `follow-hint-new-buffer-focus', but use `nosave-buffer's."
+  (query-hints "Select elements"
                (lambda (result)
                  (%follow-hint-nosave-buffer-focus (first result))
                  (mapcar #'%follow-hint-nosave-buffer (rest result)))))
 
 (define-command copy-hint-url ()
-  "Prompt for element hints and save its corresponding URLs to clipboard.
-Uses `%copy-hint-url' internally."
-  (query-hints "Copy element URL"
+  "Save the element hint's URL to the clipboard."
+  (query-hints "Select element"
                (lambda (result) (%copy-hint-url (first result)))
                :enable-marks-p nil
                :selector "a"))

source/mode/reading-line.lisp

@@ -51,8 +51,7 @@ Commands:
     (ps:chain (nyxt/ps:qs document "#reading-line-cursor") (scroll-into-view-if-needed))))
 
 (define-command reading-line-cursor-up (&key (step-size 20) (buffer (current-buffer)))
-  "Move the reading line cursor up. If scrolling off screen, move the
-screen as well."
+  "Move the reading line cursor up."
   (ps-eval :buffer buffer
     (let ((original-position
             (ps:chain (parse-int
@@ -62,7 +61,7 @@ screen as well."
   (jump-to-reading-line-cursor :buffer buffer))
 
 (define-command reading-line-cursor-down (&key (step-size 20) (buffer (current-buffer)))
-  "Move the reading line cursor down. If scrolling off screen, move the screen as well."
+  "Move the reading line cursor down."
   (ps-eval :buffer buffer
     (let ((original-position
             (ps:chain (parse-int

source/start.lisp

@@ -195,8 +195,7 @@ Without --remote, it also disables socket use."))))
   (quit))
 
 (define-command start-swank (&optional (swank-port *swank-port*))
-  "Start a Swank server that can be connected to, for instance, in
-Emacs via SLIME.
+  "Start a Swank server enabling connecting to Emacs via SLIME.
 
 Warning: This allows Nyxt to be controlled remotely, that is, to
 execute arbitrary code with the privileges of the user running Nyxt.
@@ -206,8 +205,7 @@ before running this command."
   (echo "Swank server started at port ~a" swank-port))
 
 (define-command start-slynk (&optional (slynk-port *slynk-port*))
-  "Start a Slynk server that can be connected to, for instance, in
-Emacs via Sly.
+  "Start a Slynk server enabling connecting to Emacs via SLY.
 
 Warning: This allows Nyxt to be controlled remotely, that is, to
 execute arbitrary code with the privileges of the user running Nyxt.