Comment parameter/return types above functions

I find this helps readability, at least for me.

mirror-img.lisp

@@ -25,6 +25,7 @@
 
 ;;; Mirror-img
 ;;; ————————————————————————————————————————
+;; pathname pathname list → string
 (defun mirror-img (html-file base-dir &optional (tags '("img")))
   "Attempt to mirror all remote HREF/SRC URLs of an HTML file’s tags,
 downloading them to base-dir. The remote URLs will be replaced with the
@@ -42,6 +43,7 @@ Returns a string of the modified page’s HTML."
     (aref (lquery:$ dom (serialize)) 0)))
 
 
+;; lquery-dom list pathname → alist
 (defun mirror-linked-urls (dom &optional (tags '("link" "img" "script")) base-dir)
   "Mirror all URLs in the HREF/SRC attributes of the given tags in an LQuery
 DOM, downloading them to either the current-working directory or the base-dir.
@@ -60,6 +62,7 @@ For example:
     (linked-urls dom tags))))
 
 
+;; lquery-dom alist list → nil
 (defun substitute-urls (dom substitution-alist &optional (tags '("img")))
   "Replace SRC or HREF attributes of certain tags in an LQuery DOM, based on a
 substitution associative list. The substitution alist is made up of cons-cells
@@ -81,6 +84,7 @@ among the given tags."
   dom)
 
 
+;; string pathname → pathname
 (defun mirrored-pathname (url &optional base-dir)
   "Given a URL, return the corresponding path we would download it to, were we
 to mirror it."
@@ -97,6 +101,7 @@ to mirror it."
 
 ;;; DOM-parsing
 ;;; ————————————————————————————————————————
+;; lquery-dom list → list
 (defun linked-urls (dom &optional (tags '("link" "img" "script")))
   "Return a list of all URLs in the LQuery DOM contained in the given tags’
 HREF and SRC attributes."
@@ -110,6 +115,7 @@ HREF and SRC attributes."
           append (url-list-of-tag tag))))
 
 
+;; lquery-node → string
 (defun node-url (node)
   "Return the SRC or HREF attribute of an LQuery node, if such a thing exists."
   (and node
@@ -117,6 +123,7 @@ HREF and SRC attributes."
            (lquery-funcs:attr node "href"))))
 
 
+;; lquery-node → nil
 (defun set-node-url (node url)
   "Set the SRC or HREF attribute of an LQuery node (based on which attribute is
 already set)."
@@ -130,6 +137,7 @@ already set)."
 
 ;;; Util
 ;;; ————————————————————————————————————————
+;; string pathname → pathname or nil
 (defun http-fetch (url path)
   "Download a URL to a path; if successful, returns the pathname. Otherwise, NIL."
   (handler-case
@@ -140,6 +148,7 @@ already set)."
     (error nil)))
 
 
+;; string → string
 (defun url-encode-uri (uri)
  "URL-encode the path component of a URI. For example,
 “https://invalid.tld/dad alive.jpg” → “https://invalid.tld/dad%20alive.jpg”"
@@ -151,6 +160,7 @@ already set)."
             (url-encode-path (quri:uri-path uri)))))
 
 
+;; string → string
 (defun url-encode-path (path)
   "URL-encode a pathname’s components (directory and filenames). For example,
 “/images!/dad alive.jpg” → “/images%21/dad%20alive.jpg”"