From ba9005587b045d417b460f59145032f569c95cba Mon Sep 17 00:00:00 2001
From: Asko Nõmm <asko@apesrc.com>
Date: Wed, 11 Feb 2026 01:53:02 +0200
Subject: Allow docstrings in `defhtml` (closes #2)

---
 src/dompa/nodes.cljc       | 13 ++++++++++---
 test/dompa/nodes_test.cljc | 18 ++++++++++++++++++
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/src/dompa/nodes.cljc b/src/dompa/nodes.cljc
index 58ff045..7e8f769 100644
--- a/src/dompa/nodes.cljc
+++ b/src/dompa/nodes.cljc
@@ -95,10 +95,14 @@
 (defmacro defhtml
   "Creates a new function with `name` that outputs HTML.
 
+  Optionally accepts a docstring between the name and the argument vector.
+
   Example usage:
 
   ```clojure
-  (defhtml about-page [who]
+  (defhtml about-page
+    \"Renders the about page for the given person.\"
+    [who]
     ($ :div
       ($ \"hello \" who)))
 
@@ -106,8 +110,11 @@
   ```
   "
   [name & args-and-elements]
-  (let [[args & elements] args-and-elements]
-    `(defn ~name ~args
+  (let [[maybe-doc & rest] args-and-elements
+        [docstring args elements] (if (string? maybe-doc)
+                                    [maybe-doc (first rest) (next rest)]
+                                    [nil maybe-doc rest])]
+    `(defn ~name ~@(when docstring [docstring]) ~args
        (->html (vector ~@elements)))))
 
 (defn- list-of-one?
diff --git a/test/dompa/nodes_test.cljc b/test/dompa/nodes_test.cljc
index 0340abb..e7c6616 100644
--- a/test/dompa/nodes_test.cljc
+++ b/test/dompa/nodes_test.cljc
@@ -16,10 +16,28 @@
   ($ :div
      ($ "hello " who)))
 
+(defhtml hello-with-doc
+  "Greets the given person with a div."
+  [who]
+  ($ :div
+     ($ "hello " who)))
+
 (deftest defhtml-test
   (is (= "<div>hello world</div>"
          (hello "world"))))
 
+(deftest defhtml-docstring-test
+  (testing "defhtml with docstring produces correct HTML"
+    (is (= "<div>hello world</div>"
+           (hello-with-doc "world"))))
+  #?(:clj
+     (testing "docstring is attached to the var metadata"
+       (is (= "Greets the given person with a div."
+              (:doc (meta #'hello-with-doc))))))
+  #?(:clj
+     (testing "defhtml without docstring has no :doc metadata"
+       (is (nil? (:doc (meta #'hello)))))))
+
 (defhtml list-items [items]
   ($ :ul
      (->> items
-- 
cgit v1.2.3