Also add docstrings for mode-line-format-right-align definitions

1 files changed, 24 insertions, 0 deletions

diff --git a/emacs/init.el b/emacs/init.el
index f548346..5b02411 100644
--- a/emacs/init.el
+++ b/emacs/init.el
@@ -87,12 +87,35 @@
 
 ;; Copy the code from mode-line-format-right-align so that i can use it.  This is an emacs 30 feature, which i don't run yet.  In the future, i'll be able to remove this.
 (defcustom mode-line-right-align-edge 'window
+  "Where function `mode-line-format-right-align' should align to.
+Internally, that function uses `:align-to' in a display property,
+so aligns to the left edge of the given area.  See info node
+`(elisp)Pixel Specification'.
+
+Must be set to a symbol.  Acceptable values are:
+- `window': align to extreme right of window, regardless of margins
+  or fringes
+- `right-fringe': align to right-fringe
+- `right-margin': align to right-margin"
   :type '(choice (const right-margin)
                  (const right-fringe)
                  (const window))
   :group 'mode-line
   :version "30.1")
 (defun mode--line-format-right-align ()
+  "Right-align all following mode-line constructs.
+
+When the symbol `mode-line-format-right-align' appears in
+`mode-line-format', return a string of one space, with a display
+property to make it appear long enough to align anything after
+that symbol to the right of the rendered mode line.  Exactly how
+far to the right is controlled by `mode-line-right-align-edge'.
+
+It is important that the symbol `mode-line-format-right-align' be
+included in `mode-line-format' (and not another similar construct
+such as `(:eval (mode-line-format-right-align)').  This is because
+the symbol `mode-line-format-right-align' is processed by
+`format-mode-line' as a variable."
   (let* ((rest (cdr (memq 'mode-line-format-right-align
 			  mode-line-format)))
 	 (rest-str (format-mode-line `("" ,@rest)))
@@ -120,6 +143,7 @@
                                             (or (cadr (window-fringes)) 0))
                                            (_ 0))
                                          rest-width)))))))
+
 (defvar mode-line-format-right-align '(:eval (mode--line-format-right-align))
   "Mode line construct to right align all following constructs.")
 (put 'mode-line-format-right-align 'risky-local-variable t)