Document the $inline tag (#285)

fixes #284

doc.go

@@ -130,7 +130,7 @@
 // query results. The edgedb.Optional struct can be embedded to make structs
 // optional.
 //
-//	type User Struct {
+//	type User struct {
 //	    edgedb.Optional
 //	    Email string `edgedb:"email"`
 //	}
@@ -154,6 +154,19 @@
 // Nested structures are also not directly allowed but you can use [json]
 // instead.
 //
+// By default EdgeDB will ignore embedded structs when marshaling/unmarshaling.
+// To treat an embedded struct's fields as part of the parent struct's fields,
+// tag the embedded struct with `edgedb:"$inline"`.
+//
+//	type Object struct {
+//	    ID edgedb.UUID
+//	}
+//
+//	type User struct {
+//	    Object `edgedb:"$inline"`
+//	    Name string
+//	}
+//
 // # Custom Marshalers
 //
 // Interfaces for user defined marshaler/unmarshalers  are documented in the

internal/cmd/gendocs/rstprinter.go

@@ -114,5 +114,6 @@ func (p *rstPrinter) text(out *bytes.Buffer, x []comment.Text) {
 func (p *rstPrinter) escape(out *bytes.Buffer, s string) {
 	s = strings.ReplaceAll(s, "*", "\\*")
 	s = strings.ReplaceAll(s, "\\\\*", "\\*")
+	s = strings.ReplaceAll(s, "`", "\\`")
 	out.WriteString(s)
 }

rstdocs/index.rst

@@ -148,7 +148,7 @@ optional.
 
 .. code-block:: go
 
-    type User Struct {
+    type User struct {
         edgedb.Optional
         Email string `edgedb:"email"`
     }
@@ -174,6 +174,21 @@ using sets as parameters.
 Nested structures are also not directly allowed but you can use `json <https://www.edgedb.com/docs/edgeql/insert#bulk-inserts>`_
 instead.
 
+By default EdgeDB will ignore embedded structs when marshaling/unmarshaling.
+To treat an embedded struct's fields as part of the parent struct's fields,
+tag the embedded struct with \`edgedb:"$inline"\`.
+
+.. code-block:: go
+
+    type Object struct {
+        ID edgedb.UUID
+    }
+    
+    type User struct {
+        Object `edgedb:"$inline"`
+        Name string
+    }
+    
 
 Custom Marshalers
 -----------------