(DOCSP-14648): Error handling (#997)

* (DOCSP-14648): Error handling

* Re-add missing on-this-page

Author: cbush

examples/ios/Examples/OpenCloseRealm.m

@@ -73,6 +73,19 @@ - (void)testConfigureObjectTypes {
     (void)realm;
 }
 
+- (void)testHandleError {
+    // :code-block-start: handle-error
+    NSError *error = nil;
+    RLMRealmConfiguration *config = [RLMRealmConfiguration defaultConfiguration];
+    RLMRealm *realm = [RLMRealm realmWithConfiguration:config error:&error];
+    if (!realm) {
+        // Handle error
+        return;
+    }
+    // Use realm
+    // :code-block-end:
+}
+
 @end
 
 // :replace-end:

examples/ios/Examples/OpenCloseRealm.swift

@@ -52,4 +52,15 @@ class OpenCloseRealm: XCTestCase {
         // :code-block-end:
         print(fileUrl)
     }
+    
+    func testHandleError() {
+        // :code-block-start: handle-error
+        do {
+            let realm = try Realm()
+            // Use realm
+        } catch let error as NSError {
+            // Handle error
+        }
+        // :code-block-end:
+    }
 }

source/examples/generated/code/start/OpenCloseRealm.codeblock.handle-error.m

@@ -0,0 +1,8 @@
+NSError *error = nil;
+RLMRealmConfiguration *config = [RLMRealmConfiguration defaultConfiguration];
+RLMRealm *realm = [RLMRealm realmWithConfiguration:config error:&error];
+if (!realm) {
+    // Handle error
+    return;
+}
+// Use realm

source/examples/generated/code/start/OpenCloseRealm.codeblock.handle-error.swift

@@ -0,0 +1,6 @@
+do {
+    let realm = try Realm()
+    // Use realm
+} catch let error as NSError {
+    // Handle error
+}

source/sdk/ios/examples/configure-and-open-a-realm.txt

@@ -4,6 +4,14 @@
 Configure & Open a Realm - iOS SDK
 ==================================
 
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
 A **{+realm+}** is the core data structure used to organize data in
 {+client-database+}. For more information, see :ref:`ios-realms`.
 
@@ -67,6 +75,32 @@ When a {+realm+} goes out of scope and is removed from memory due to
 <https://docs.swift.org/swift-book/LanguageGuide/AutomaticReferenceCounting.html>`__,
 the {+realm+} is closed.
 
+.. _ios-handle-errors:
+
+Handle Errors
+-------------
+
+.. tabs-realm-languages::
+   
+   .. tab::
+      :tabid: swift
+
+      To handle errors when accessing a {+realm+}, use Swift's built-in
+      error handling mechanism:
+
+      .. literalinclude:: /examples/generated/code/start/OpenCloseRealm.codeblock.handle-error.swift
+         :language: swift
+
+   .. tab::
+      :tabid: objective-c
+
+      To handle errors when accessing a {+realm+}, provide an
+      ``NSError`` pointer to the ``error`` parameter:
+
+      .. literalinclude:: /examples/generated/code/start/OpenCloseRealm.codeblock.handle-error.m
+         :language: objectivec
+
+
 .. _ios-open-an-in-memory-realm:
 
 Open an In-Memory Realm
@@ -102,6 +136,12 @@ closed.
       .. literalinclude:: /examples/generated/code/start/OpenCloseRealm.codeblock.open-in-memory-realm.m
          :language: objectivec
 
+.. important::
+
+   When all *in-memory* {+realm+} instances with a particular identifier
+   go out of scope, {+client-database+} deletes **all data** in that
+   {+realm+}. To avoid this, hold onto a strong reference to any
+   in-memory {+realms+} during your app's lifetime. 
 
 .. _ios-provide-a-subset-of-classes-to-a-realm: