[PATCH] Improve docstrings of agenda date navigation commands

[PATCH] Improve docstrings of agenda date navigation commands

[Stefan Kangas]

[-- Attachment #1.1: Type: text/plain, Size: 206 bytes --]

I found the docstrings of the agenda date navigation commands to be
somewhat lacking.  The attached patch expands them slightly and adds
crossreferences, which I think makes them much more usable.  Thanks.

[-- Attachment #1.2: Type: text/html, Size: 234 bytes --]

[-- Attachment #2: 0001-Improve-docstrings-of-agenda-date-navigation-command.patch --]
[-- Type: application/octet-stream, Size: 3153 bytes --]

From 21734facbcdb2a10104fb0d8d8f6159590951d1f Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Mon, 20 Jun 2022 14:06:51 +0200
Subject: [PATCH] Improve docstrings of agenda date navigation commands

* lisp/org-agenda.el (org-agenda-goto-date)
(org-agenda-goto-today, org-agenda-later, org-agenda-earlier):
Improve documentation and add crossreferences.
---
 lisp/org-agenda.el | 36 ++++++++++++++++++++++++++++++------
 1 file changed, 30 insertions(+), 6 deletions(-)

diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index b4e5547d7..477439401 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -8319,7 +8319,16 @@ Negative selection means regexp must not match for selection of an entry."
   (set var (concat (symbol-value var) string)))
 
 (defun org-agenda-goto-date (date)
-  "Jump to DATE in agenda."
+  "Jump to DATE in the agenda buffer.
+
+When called interactively, prompt for the date.
+When called from Lisp, DATE should be a date as returned by
+`org-read-date'.
+
+See also:
+ `org-agenda-earlier'    (\\[org-agenda-earlier])
+ `org-agenda-later'      (\\[org-agenda-later])
+ `org-agenda-goto-today' (\\[org-agenda-goto-today])"
   (interactive
    (list
     (let ((org-read-date-prefer-future org-agenda-jump-prefer-future))
@@ -8351,7 +8360,12 @@ Negative selection means regexp must not match for selection of an entry."
 	    org-agenda-this-buffer-is-sticky org-agenda-sticky))))
 
 (defun org-agenda-goto-today ()
-  "Go to today."
+  "Go to today's date in the agenda buffer.
+
+See also:
+ `org-agenda-later'     (\\[org-agenda-later])
+ `org-agenda-earlier'   (\\[org-agenda-earlier])
+ `org-agenda-goto-date' (\\[org-agenda-goto-date])"
   (interactive)
   (org-agenda-check-type t 'agenda)
   (let* ((args (get-text-property (min (1- (point-max)) (point)) 'org-last-args))
@@ -8410,8 +8424,13 @@ When optional argument BACKWARD is set, go backward."
 	       (message "No %s block" (if backward "previous" "further")))))))
 
 (defun org-agenda-later (arg)
-  "Go forward in time by the current span.
-With prefix ARG, go forward that many times the current span."
+  "Go forward in time by the current span in the agenda buffer.
+With prefix ARG, go forward that many times the current span.
+
+See also:
+ `org-agenda-earlier'    (\\[org-agenda-earlier])
+ `org-agenda-goto-today' (\\[org-agenda-goto-today])
+ `org-agenda-goto-date'  (\\[org-agenda-goto-date])"
   (interactive "p")
   (org-agenda-check-type t 'agenda)
   (let* ((wstart (window-start))
@@ -8452,8 +8471,13 @@ With prefix ARG, go forward that many times the current span."
     (set-window-start nil wstart)))
 
 (defun org-agenda-earlier (arg)
-  "Go backward in time by the current span.
-With prefix ARG, go backward that many times the current span."
+  "Go backward in time by the current span in the agenda buffer.
+With prefix ARG, go backward that many times the current span.
+
+See also:
+ `org-agenda-later'      (\\[org-agenda-later])
+ `org-agenda-goto-today' (\\[org-agenda-goto-today])
+ `org-agenda-goto-date'  (\\[org-agenda-goto-date])"
   (interactive "p")
   (org-agenda-later (- arg)))
 
-- 
2.33.0

Re: [PATCH] Improve docstrings of agenda date navigation commands

[Daniel Fleischer]

Stefan Kangas [2022-06-20 Mon 17:54] wrote:

> I found the docstrings of the agenda date navigation commands to be somewhat lacking.  The attached patch expands them
> slightly and adds crossreferences, which I think makes them much more usable.  Thanks.

Thanks, looks good. Merged at e7e37c5b2.

Best, 

-- 

Daniel Fleischer