1 files changed, 16 insertions, 5 deletions
diff --git a/src/dompa/nodes.cljc b/src/dompa/nodes.cljc
index 7e8f769..73bc11f 100644
--- a/src/dompa/nodes.cljc
+++ b/src/dompa/nodes.cljc
@@ -96,17 +96,24 @@
   "Creates a new function with `name` that outputs HTML.
 
   Optionally accepts a docstring between the name and the argument vector.
+  
+  Functions created with `defhtml` can be nested and composed with each other.
 
   Example usage:
 
   ```clojure
+  (defhtml greeting [who]
+    ($ :span who))
+
   (defhtml about-page
-    \"Renders the about page for the given person.\"
+    \"Renders the about page.\"
     [who]
     ($ :div
-      ($ \"hello \" who)))
+       \"Hello, \"
+       (greeting who)))
 
   (about-page \"world\")
+  ;;=> \"<div>Hello, <span>world</span></div>\"
   ```
   "
   [name & args-and-elements]
@@ -182,13 +189,17 @@
       (first nodes))))
 
 (defn $
-  "Creates a new node
+  "Creates a new node.
   
+  Children can be passed directly - strings, numbers, and other values
+  are automatically converted to text nodes. Nil values are filtered out.
+
   Usage:
 
   ```clojure
-  ($ :div
-    ($ \"hello world\" ))
+  ($ :div \"hello world\")
+  ($ :div {:class \"container\"} \"Hello, \" name \"!\")
+  ($ :<> \"one\" \"two\" \"three\")
   ```"
   [& opts]
   (if (keyword? (first opts))