Add docstrings

README.org

@@ -249,6 +249,7 @@ The rationale behind using ~list-buffers~ is the same as with dired. They both d
 Seems to be one of the most reliable tools in the basket... mostly because
 #+begin_src elisp
 (defun gptel-org-tool--list-buffers (&optional arg)
+  "Return list of buffers."
   (list-buffers-noselect)
   (with-current-buffer "*Buffer List*"
 		    (let ((content (buffer-string)))
@@ -277,6 +278,7 @@ Be sure to customize the function to point to your org directory, if you wish. I
 
 #+begin_src elisp
 (defun gptel-org-tools--dir (dir)
+  "Return directory listing."
   (with-temp-buffer
     (dired (or dir "~"))
     (let ((content (buffer-string)))
@@ -299,6 +301,7 @@ Be sure to customize the function to point to your org directory, if you wish. I
 Disabled for now, as it's causing some issues.
 #+begin_src elisp :tangle no :results none
 (defun gptel-org-tools--find-buffer-visiting (filename)
+  "Return the buffer visiting file FILENAME."
   (concat
    (bufferp
     (find-buffer-visiting
@@ -319,6 +322,7 @@ Disabled for now, as it's causing some issues.
 Continuation from above. Open a file into a buffer for processing, once it's found by dired-list.
 #+begin_src elisp
 (defun gptel-org-tools--open-file-inactive (file)
+  "Open FILE in a buffer."
   (with-current-buffer (get-buffer-create file)
 			    (insert-file-contents file)
 			    (concat
@@ -338,6 +342,7 @@ Continuation from above. Open a file into a buffer for processing, once it's fou
 This reads file contents,
 #+begin_src elisp :tangle no
 (defun gptel-org-tools--read-file-contents (file)
+  "Return contents of FILE."
   (with-temp-buffer
                             (insert-file-contents (expand-file-name filename))
                             (concat
@@ -358,6 +363,7 @@ This reads file contents,
 **** describe-variable
 #+begin_src elisp
 (defun gptel-org-tools--describe-variable (var)
+  "Return documentation for VAR."
   (let ((symbol (intern var)))
                             (if (boundp symbol)
 				(prin1-to-string (symbol-value symbol))
@@ -377,6 +383,7 @@ This reads file contents,
 **** describe-function
 #+begin_src elisp
 (defun gptel-org-tools--describe-function (fun)
+  "Return documentation for FUN."
   (let ((symbol (intern fun)))
                             (if (fboundp symbol)
 				(prin1-to-string (documentation symbol 'function))
@@ -425,6 +432,7 @@ Pretty simple, does what it says on the tin. It gets all the tags from the =buff
 This is not, by any means, sufficient, but I do tag people and specific events frequently enough that it helps save on the context window.
 #+begin_src elisp
 (defun gptel-org-tools--org-extract-tags (buffer)
+  "Return all tags from BUFFER."
   (with-current-buffer buffer
     (let ((tags '()))
       (org-map-entries
@@ -454,6 +462,7 @@ Then we need to pull /some/ information from the buffer, without dragging the en
 Therefore, headings. A reasonable amount of information, and still keeping the signal-to-noise ratio pretty decent.
 #+begin_src elisp
 (defun gptel-org-tools--org-extract-headings (buffer)
+  "Return all headings from BUFFER."
   (if (member buffer gptel-org-tools-skip-heading-extraction)
       (user-error "Buffer %s has too many headings, use org-extract-tags or org-ql-select-rifle." buffer)
     (with-current-buffer buffer
@@ -489,6 +498,9 @@ Currently *not* tangled, as I'm testing breaking out each type of query into its
 
 #+begin_src elisp :tangle no
 (defun gptel-org-tools--org-ql-select (buf query)
+  "Return entries matching QUERY from BUFFER.
+
+QUERY can be any valid org-ql-select query."
   (org-ql-select
     (get-buffer buf)
     (if (stringp query)
@@ -566,6 +578,11 @@ DATE is the date or date range to match."
 Original (works but not ideal).
 #+begin_src elisp :tangle no
 (defun gptel-org-tools--org-ql-select-by-date (buf date)
+  "Return headings from BUFFER matching DATE.
+
+DATE must be in the form of YYYY, YYYY-MM, or YYYY-MM-DD."
+
+
   (org-ql-select
     (get-buffer buf)
     `(heading ,date)
@@ -591,6 +608,7 @@ This is still work in progress, the idea is to have the LLM check my calendar an
 It works, in principle, but I haven't been able to find a use for it yet. The real challenge is in building a context where the tools integrate with each-other in a way that makes sense. For now, this exists.
 #+begin_src elisp
 (defun gptel-org-tools--org-agenda-seek (days)
+  "Return the results of org-agenda-list spanning now to DAYS."
   (with-temp-buffer
     (org-agenda-list (or days 14))
     (let ((content (buffer-string)))
@@ -616,6 +634,7 @@ The following tools are still very much WIP, and I think they're self-explanator
 Retrieve the headings where the heading matches query..
 #+begin_src elisp
 (defun gptel-org-tools--org-ql-select-headings (buf query)
+  "Return headings matching QUERY from BUFFER."
   (org-ql-select
     (get-buffer buf)
     `(heading ,query)
@@ -640,6 +659,7 @@ Retrieve the headings where the heading matches query..
 Retrieve all the headings where either heading or content matches query.
 #+begin_src elisp
 (defun gptel-org-tools--org-ql-select-headings-rifle (buf query)
+  "Return headings of entries (body included) that match keyword QUERY from BUFFER."
   (org-ql-select
     (get-buffer buf)
     `(rifle ,query)
@@ -664,6 +684,7 @@ Retrieve all the headings where either heading or content matches query.
 This pulls all the headings (and their contents) when they match tags (without inheritance.)
 #+begin_src elisp
 (defun gptel-org-tools--org-ql-select-tags-local (buf query)
+  "Return entries whose tags match QUERY in BUFFER, without inheritance."
   (org-ql-select
     (get-buffer buf)
     `(tags-local ,query)
@@ -688,6 +709,7 @@ This pulls all the headings (and their contents) when they match tags (without i
 This pulls all the local tags (without inheritance) from buffer, and returns the number of these tagged headings.
 #+begin_src elisp
 (defun gptel-org-tools--org-ql-select-tags-local-count (buf query)
+  "Return count of entries tagged QUERY in BUFFER."
   (length (org-ql-select
 	    (get-buffer buf)
 	    `(tags-local ,query)
@@ -712,6 +734,7 @@ This pulls all the local tags (without inheritance) from buffer, and returns the
 This pulls all the headings (and their contents) when they match tags (with inheritance; if a parent entry has the tag, descendant entries do, too.)
 #+begin_src elisp
 (defun gptel-org-tools--org-ql-select-tags (buf query)
+      "Return every entry tagged QUERY from BUFFER."
   (org-ql-select
     (get-buffer buf)
     `(tags ,query)
@@ -735,6 +758,7 @@ This pulls all the headings (and their contents) when they match tags (with inhe
 And, the "grab everything that matches" tool.
 #+begin_src elisp
 (defun gptel-org-tools--org-ql-select-rifle (buf query)
+    "Return every entry matching keyword QUERY from BUFFER."
   (let ((buffer (get-buffer buf)))
     (if buffer
         (org-ql-select
@@ -761,6 +785,8 @@ And, the "grab everything that matches" tool.
 This pulls all the headings (and their contents) when they match tags (without inheritance.)
 #+begin_src elisp
 (defun gptel-org-tools--org-ql-select-all-tags-local (query)
+    "Return entries whose tags match QUERY in org-agenda-files.
+  QUERY is the tag to search for."
   (org-ql-select
     (org-agenda-files)
     `(tags-local ,query)
@@ -782,6 +808,9 @@ This pulls all the headings (and their contents) when they match tags (without i
 This pulls all the headings (and their contents) when they match tags (with inheritance; if a parent entry has the tag, descendant entries do, too.)
 #+begin_src elisp
 (defun gptel-org-tools--org-ql-select-all-tags (query)
+    "Return entries whose tags match QUERY,
+with inheritance, in org-agenda-files.
+  QUERY is the tag to search for."
   (org-ql-select
     (org-agenda-files)
     `(tags ,query)
@@ -811,6 +840,8 @@ This means that /every org-mode file I have/ is part of this search.
 
 #+begin_src elisp
 (defun gptel-org-tools--org-ql-select-all-rifle (query)
+  "Return entries containing QUERY from org-agenda-files.
+  QUERY is the keyword to search for."
   (org-ql-select
     (org-agenda-files)
     `(rifle ,query)
@@ -831,11 +862,12 @@ This means that /every org-mode file I have/ is part of this search.
 ***** org-ql-select-all-regexp
 #+begin_src elisp
 (defun gptel-org-tools--org-ql-select-all-regexp (query)
-  (let ((bound-query (format "\\b%s\\b" (regexp-quote query))))
+  "Return all entries matching regexp QUERY in org-agenda-files.
+  QUERY is a regular expression."
     (org-ql-select
       (org-agenda-files)
-      `(regexp ,bound-query)
+      `(regexp ,query)
-      :action #'gptel-org-tools--heading-body)))
+      :action #'gptel-org-tools--heading-body))
 
 (add-to-list 'gptel-org-tools
 	     (gptel-make-tool
@@ -848,7 +880,6 @@ This means that /every org-mode file I have/ is part of this search.
 	      :category "org-ql"))
 #+end_src
 
-
 ** End
 #+begin_src elisp
 (provide 'gptel-org-tools)

gptel-org-tools.el

@@ -62,6 +62,7 @@
    "---\n"))
 
 (defun gptel-org-tool--list-buffers (&optional arg)
+  "Return list of buffers."
   (list-buffers-noselect)
   (with-current-buffer "*Buffer List*"
 		    (let ((content (buffer-string)))
@@ -79,6 +80,7 @@
 	      :category "emacs"))
 
 (defun gptel-org-tools--dir (dir)
+  "Return directory listing."
   (with-temp-buffer
     (dired (or dir "~"))
     (let ((content (buffer-string)))
@@ -97,6 +99,7 @@
 	      :category "filesystem"))
 
 (defun gptel-org-tools--open-file-inactive (file)
+  "Open FILE in a buffer."
   (with-current-buffer (get-buffer-create file)
 			    (insert-file-contents file)
 			    (concat
@@ -112,6 +115,7 @@
 	      :category "filesystem"))
 
 (defun gptel-org-tools--describe-variable (var)
+  "Return documentation for VAR."
   (let ((symbol (intern var)))
                             (if (boundp symbol)
 				(prin1-to-string (symbol-value symbol))
@@ -128,6 +132,7 @@
               :category "emacs"))
 
 (defun gptel-org-tools--describe-function (fun)
+  "Return documentation for FUN."
   (let ((symbol (intern fun)))
                             (if (fboundp symbol)
 				(prin1-to-string (documentation symbol 'function))
@@ -145,6 +150,7 @@
               :category "emacs"))
 
 (defun gptel-org-tools--org-extract-tags (buffer)
+  "Return all tags from BUFFER."
   (with-current-buffer buffer
     (let ((tags '()))
       (org-map-entries
@@ -167,6 +173,7 @@
 	      :category "org-mode"))
 
 (defun gptel-org-tools--org-extract-headings (buffer)
+  "Return all headings from BUFFER."
   (if (member buffer gptel-org-tools-skip-heading-extraction)
       (user-error "Buffer %s has too many headings, use org-extract-tags or org-ql-select-rifle." buffer)
     (with-current-buffer buffer
@@ -216,6 +223,7 @@ DATE is the date or date range to match."
               :category "org"))
 
 (defun gptel-org-tools--org-agenda-seek (days)
+  "Return the results of org-agenda-list spanning now to DAYS."
   (with-temp-buffer
     (org-agenda-list (or days 14))
     (let ((content (buffer-string)))
@@ -233,6 +241,7 @@ DATE is the date or date range to match."
 	      :category "org"))
 
 (defun gptel-org-tools--org-ql-select-headings (buf query)
+  "Return headings matching QUERY from BUFFER."
   (org-ql-select
     (get-buffer buf)
     `(heading ,query)
@@ -253,6 +262,7 @@ DATE is the date or date range to match."
 	      :category "org-ql"))
 
 (defun gptel-org-tools--org-ql-select-headings-rifle (buf query)
+  "Return headings of entries (body included) that match keyword QUERY from BUFFER."
   (org-ql-select
     (get-buffer buf)
     `(rifle ,query)
@@ -273,6 +283,7 @@ DATE is the date or date range to match."
 	      :category "org-ql"))
 
 (defun gptel-org-tools--org-ql-select-tags-local (buf query)
+  "Return entries whose tags match QUERY in BUFFER, without inheritance."
   (org-ql-select
     (get-buffer buf)
     `(tags-local ,query)
@@ -293,6 +304,7 @@ DATE is the date or date range to match."
 	      :category "org-ql"))
 
 (defun gptel-org-tools--org-ql-select-tags-local-count (buf query)
+  "Return count of entries tagged QUERY in BUFFER."
   (length (org-ql-select
 	    (get-buffer buf)
 	    `(tags-local ,query)
@@ -313,6 +325,7 @@ DATE is the date or date range to match."
 	      :category "org-ql"))
 
 (defun gptel-org-tools--org-ql-select-tags (buf query)
+      "Return every entry tagged QUERY from BUFFER."
   (org-ql-select
     (get-buffer buf)
     `(tags ,query)
@@ -332,6 +345,7 @@ DATE is the date or date range to match."
 	      :category "org-ql"))
 
 (defun gptel-org-tools--org-ql-select-rifle (buf query)
+    "Return every entry matching keyword QUERY from BUFFER."
   (let ((buffer (get-buffer buf)))
     (if buffer
         (org-ql-select
@@ -354,6 +368,8 @@ DATE is the date or date range to match."
 	      :category "org-ql"))
 
 (defun gptel-org-tools--org-ql-select-all-tags-local (query)
+    "Return entries whose tags match QUERY in org-agenda-files.
+  QUERY is the tag to search for."
   (org-ql-select
     (org-agenda-files)
     `(tags-local ,query)
@@ -371,6 +387,9 @@ DATE is the date or date range to match."
 	      :category "org-ql"))
 
 (defun gptel-org-tools--org-ql-select-all-tags (query)
+    "Return entries whose tags match QUERY,
+with inheritance, in org-agenda-files.
+  QUERY is the tag to search for."
   (org-ql-select
     (org-agenda-files)
     `(tags ,query)
@@ -387,6 +406,8 @@ DATE is the date or date range to match."
 	      :category "org-ql"))
 
 (defun gptel-org-tools--org-ql-select-all-rifle (query)
+  "Return entries containing QUERY from org-agenda-files.
+  QUERY is the keyword to search for."
   (org-ql-select
     (org-agenda-files)
     `(rifle ,query)
@@ -403,11 +424,12 @@ DATE is the date or date range to match."
 	      :category "org-ql"))
 
 (defun gptel-org-tools--org-ql-select-all-regexp (query)
-  (let ((bound-query (format "\\b%s\\b" (regexp-quote query))))
+  "Return all entries matching regexp QUERY in org-agenda-files.
+  QUERY is a regular expression."
     (org-ql-select
       (org-agenda-files)
-      `(regexp ,bound-query)
+      `(regexp ,query)
-      :action #'gptel-org-tools--heading-body)))
+      :action #'gptel-org-tools--heading-body))
 
 (add-to-list 'gptel-org-tools
 	     (gptel-make-tool