From d1de2fac0ed0b2e573b0ab8f33a7fe5c2d9d322e Mon Sep 17 00:00:00 2001
From: Chase Fleming <1666730+chasefleming@users.noreply.github.com>
Date: Sat, 11 Nov 2023 12:32:41 -0800
Subject: [PATCH] Add comments and new elements to readme

---
 README.md | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 46029bf..994201d 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,8 @@ import (
 
 ### Creating Elements
 
+Here's an example of creating a `<div>` element with nested `<h1>`, `<h2>`, and `<p>` elements using elem:
+
 ```go
 content := elem.Div(attrs.Props{
     attrs.ID:    "container",
@@ -42,6 +44,16 @@ content := elem.Div(attrs.Props{
 )
 ```
 
+When the above Go code is executed and the `.Render()` method is called, it produces the following HTML:
+
+```html
+<div id="container" class="my-class">
+    <h1>Hello, Elem!</h1>
+    <h2>Subheading</h2>
+    <p>This is a paragraph.</p>
+</div>
+```
+
 ### Attributes and Styles
 
 The `attrs` subpackage provides type-safe attribute functions that ensure you're setting valid attributes for your elements. This helps eliminate potential issues at runtime due to misspelled or unsupported attribute names.
@@ -78,10 +90,14 @@ See the complete list of supported attributes in [the `attrs` package](./attrs/a
 
 ### Rendering Elements
 
+The `.Render()` method is used to convert the structured Go elements into HTML strings. This method is essential for generating the final HTML output that can be served to a web browser or integrated into templates.
+
 ```go
 html := content.Render()
 ```
 
+In this example, content refers to an elem element structure. When the `.Render()` method is called on content, it generates the HTML representation of the constructed elements.
+
 ### Generating Lists of Elements with `TransformEach`
 
 With `elem`, you can easily generate lists of elements from slices of data using the `TransformEach` function. This function abstracts the repetitive task of iterating over a slice and transforming its items into elements.
@@ -127,10 +143,19 @@ In this example, if `isAdmin` is `true`, the `Admin Panel` link is rendered. Oth
 - **Grouping Content**: `Div`, `Span`, `Li`, `Ul`, `Ol`, `Dl`, `Dt`, `Dd`
 - **Tables**: `Table`, `Tr`, `Td`, `Th`, `TBody`, `THead`, `TFoot`
 - **Hyperlinks and Multimedia**: `Img`
-- **Embedded Content**: `Iframe`
+- **Embedded Content**: `Audio`, `Iframe`, `Source`, `Video`
 - **Script-supporting Elements**: `Script`, `Noscript`
 - **Inline Semantic**: `A`, `Strong`, `Em`, `Code`, `I`
 
+### Additional Utility: HTML Comments
+
+Apart from standard elements, `elem-go` also allows you to insert HTML comments using the `Comment` function:
+
+```go
+comment := elem.Comment("Section: Main Content Start")
+// Generates: <!-- Section: Main Content Start -->
+```
+
 ## HTMX Integration
 
 We provide a subpackage for htmx integration. [Read more about htmx integration here](HTMX_INTEGRATION.md).