diff --git a/src/pages/docs/messages/annotations.mdx b/src/pages/docs/messages/annotations.mdx
index 7526a4677d..ef24b54124 100644
--- a/src/pages/docs/messages/annotations.mdx
+++ b/src/pages/docs/messages/annotations.mdx
@@ -249,6 +249,37 @@ channel.annotations.publish(message, annotation);
 // You can also use a message's `serial`
 channel.annotations.publish(message.serial, annotation);
 ```
+
+```swift
+// Create an Ably Realtime client specifying the clientId that will
+// be associated with annotations published by this client
+let options = ARTClientOptions(key: "{{API_KEY}}")
+options.clientId = "my-client-id"
+let realtime = ARTRealtime(options: options)
+
+// Create a channel in a namespace called `annotations`
+// which has message annotations enabled
+let channel = realtime.channels.get("annotations:example")
+
+// Publish an annotation for a message that flags it as delivered
+let annotation = ARTOutboundAnnotation(
+    id: nil,
+    type: "receipts:flag.v1",
+    clientId: nil,
+    name: "delivered",
+    count: nil,
+    data: nil,
+    extras: nil
+)
+channel.annotations.publish(for: message, annotation: annotation) { error in
+    // Handle error if needed
+}
+
+// You can also use a message's `serial`
+channel.annotations.publish(forMessageSerial: messageSerial, annotation: annotation) { error in
+    // Handle error if needed
+}
+```
 </Code>
 
 In the case of the `distinct`, `unique`, or `multiple` aggregation types, you should also specify a `name`. For these types, each different name will be aggregated separately in the [annotation summary](#annotation-summaries).
@@ -280,6 +311,22 @@ annotation.count = 4;
 
 channel.annotations.publish(message.serial, annotation);
 ```
+
+```swift
+let annotation = ARTOutboundAnnotation(
+    id: nil,
+    type: "rating:multiple.v1",
+    clientId: nil,
+    name: "stars",
+    count: 4,
+    data: nil,
+    extras: nil
+)
+
+channel.annotations.publish(forMessageSerial: message.serial, annotation: annotation) { error in
+    // Handle error if needed
+}
+```
 </Code>
 
 You can additionally specify a `data` payload when publishing an annotation. This is not included in an annotation summary, so only readable by [clients that are subscribed to individual annotation events](#individual-annotations).
@@ -344,6 +391,32 @@ annotation.type = "receipts:flag.v1";
 annotation.name = "delivered";
 channel.annotations.delete(message.serial, annotation);
 ```
+
+```swift
+// Create an Ably Realtime client specifying the clientId that will
+// be associated with annotations published by this client
+let options = ARTClientOptions(key: "{{API_KEY}}")
+options.clientId = "my-client-id"
+let realtime = ARTRealtime(options: options)
+
+// Create a channel in a namespace called `annotations`
+// which has message annotations enabled
+let channel = realtime.channels.get("annotations:example")
+
+// Delete a 'delivered' annotation
+let annotation = ARTOutboundAnnotation(
+    id: nil,
+    type: "receipts:flag.v1",
+    clientId: nil,
+    name: "delivered",
+    count: nil,
+    data: nil,
+    extras: nil
+)
+channel.annotations.delete(forMessageSerial: message.serial, annotation: annotation) { error in
+    // Handle error if needed
+}
+```
 </Code>
 
 ## Subscribe to annotation summaries <a id="subscribe" />
@@ -408,6 +481,24 @@ channel.subscribe(message -> {
   }
 });
 ```
+
+```swift
+// Create an Ably Realtime client specifying the clientId that will
+// be associated with annotations published by this client
+let options = ARTClientOptions(key: "{{API_KEY}}")
+options.clientId = "my-client-id"
+let realtime = ARTRealtime(options: options)
+
+// Create a channel in a namespace called `annotations`
+// which has message annotations enabled
+let channel = realtime.channels.get("annotations:example")
+
+channel.subscribe { message in
+  if message.action == .messageSummary {
+    print(message.annotations?.summary ?? [:])
+  }
+}
+```
 </Code>
 
 ### Annotation summaries <a id="annotation-summaries"/>
@@ -564,6 +655,26 @@ channel.annotations.subscribe(annotation -> {
   }
 });
 ```
+
+```swift
+// Create an Ably Realtime client specifying the clientId that will
+// be associated with annotations published by this client
+let options = ARTClientOptions(key: "{{API_KEY}}")
+options.clientId = "my-client-id"
+let realtime = ARTRealtime(options: options)
+
+// Create a channel in a namespace called `annotations`
+// which has message annotations enabled
+let channel = realtime.channels.get("annotations:example")
+
+channel.annotations.subscribe { annotation in
+  if annotation.action == .create {
+    print("New \(annotation.type) annotation with name \(annotation.name ?? "") from \(annotation.clientId ?? "")")
+  } else if annotation.action == .delete {
+    print("\(annotation.clientId ?? "") deleted a \(annotation.type) annotation with name \(annotation.name ?? "")")
+  }
+}
+```
 </Code>
 
 ### Annotation message properties <a id="annotation-properties"/>