Merge pull request #3652 from realm/az-ce-1

Additional copyediting and polish

Realm/RLMMigration.h

@@ -82,7 +82,6 @@ typedef void (^RLMObjectMigrationBlock)(RLMObject * __nullable oldObject, RLMObj
                     an `NSArray` containing one element for each persisted property. An exception will be
                     thrown if any required properties are not present and those properties were not defined with
                     default values.
-
                     When passing in an `NSArray`, all properties must be present,
                     valid and in the same order as the properties defined in the model.
  */

Realm/RLMObject.h

@@ -98,7 +98,7 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  Initializes an unmanaged instance of a Realm object.
 
- Call `addObject:` on a `RLMRealm` instance to add an unmanaged object into that Realm.
+ Call `addObject:` on an `RLMRealm` instance to add an unmanaged object into that Realm.
  
  @see `[RLMRealm addObject:]`
  */
@@ -110,7 +110,7 @@ NS_ASSUME_NONNULL_BEGIN
  
  Pass in an `NSArray` or `NSDictionary` instance to set the values of the object's properties.
 
- Call `addObject:` on a `RLMRealm` instance to add an unmanaged object into that Realm.
+ Call `addObject:` on an `RLMRealm` instance to add an unmanaged object into that Realm.
  
  @see `[RLMRealm addObject:]`
  */
@@ -138,7 +138,6 @@ NS_ASSUME_NONNULL_BEGIN
                  an `NSArray` containing one element for each persisted property. An exception will be
                  thrown if any required properties are not present and those properties were not defined with
                  default values.
-
                  When passing in an `NSArray`, all properties must be present,
                  valid and in the same order as the properties defined in the model.
 
@@ -158,7 +157,6 @@ NS_ASSUME_NONNULL_BEGIN
                  an `NSArray` containing one element for each persisted property. An exception will be
                  thrown if any required properties are not present and those properties were not defined with
                  default values.
-
                  When passing in an `NSArray`, all properties must be present,
                  valid and in the same order as the properties defined in the model.
 
@@ -184,7 +182,6 @@ NS_ASSUME_NONNULL_BEGIN
                  an `NSArray` containing one element for each persisted property. An exception will be
                  thrown if any required properties are not present and those properties were not defined with
                  default values.
-
                  When passing in an `NSArray`, all properties must be present,
                  valid and in the same order as the properties defined in the model.
 
@@ -211,7 +208,6 @@ NS_ASSUME_NONNULL_BEGIN
                  an `NSArray` containing one element for each persisted property. An exception will be
                  thrown if any required properties are not present and those properties were not defined with
                  default values.
-
                  When passing in an `NSArray`, all properties must be present,
                  valid and in the same order as the properties defined in the model.
 

Realm/RLMRealm.h

@@ -34,7 +34,7 @@ NS_ASSUME_NONNULL_BEGIN
  within a single iteration of the run loop will normally return the same
  `RLMRealm` object.
  
- If you specifically want to ensure a `RLMRealm` instance is
+ If you specifically want to ensure an `RLMRealm` instance is
  destroyed (for example, if you wish to open a Realm, check some property, and
  then possibly delete the Realm file and re-open it), place the code which uses
  the Realm within an `@autoreleasepool {}` and ensure you have no other
@@ -56,7 +56,7 @@ NS_ASSUME_NONNULL_BEGIN
  Obtains an instance of the default Realm.
 
  The default Realm is used by the `RLMObject` class methods
- which do not take a `RLMRealm` parameter, but is otherwise not special. The
+ which do not take an `RLMRealm` parameter, but is otherwise not special. The
  default Realm is persisted as default.realm under the Documents directory of
  your Application on iOS, and in your application's Application Support
  directory on OS X.
@@ -97,10 +97,9 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  Indicates if the Realm is currently engaged in a write transaction.
 
- @warning Wrapping mutating operations in a write transaction if this property returns `NO`
-          may cause a large number of write transactions to be created, which could negatively
-          impact Realm's performance. Always prefer performing multiple mutations in a single
-          transaction when possible.
+ @warning   Do not simply check this property and then start a write transaction whenever an object needs to be
+            created, updated, or removed. Doing so might cause a large number of write transactions to be created,
+            degrading performance. Instead, always prefer performing multiple updates during a single transaction.
  */
 @property (nonatomic, readonly) BOOL inWriteTransaction;
 
@@ -277,7 +276,7 @@ typedef void (^RLMNotificationBlock)(NSString *notification, RLMRealm *realm);
  will need to manually call `-refresh` in order to update to the latest version,
  even if `autorefresh` is set to `YES`.
 
- Even with this enabled, you can still call `-refresh` at any time to update the
+ Even with this property enabled, you can still call `-refresh` at any time to update the
  Realm before the automatic refresh would occur.
 
  Notifications are sent when a write transaction is committed whether or not
@@ -315,7 +314,7 @@ typedef void (^RLMNotificationBlock)(NSString *notification, RLMRealm *realm);
 - (BOOL)writeCopyToURL:(NSURL *)fileURL encryptionKey:(nullable NSData *)key error:(NSError **)error;
 
 /**
- Invalidates all `RLMObject`s and `RLMResults` managed by the Realm.
+ Invalidates all `RLMObject`s, `RLMResults`, `RLMLinkingObjects`, and `RLMArray`s managed by the Realm.
 
  A Realm holds a read lock on the version of the data accessed by it, so
  that changes made to the Realm on different threads do not modify or delete the

Realm/RLMRealm_Dynamic.h

@@ -91,7 +91,7 @@
 - (RLMObject *)objectWithClassName:(NSString *)className forPrimaryKey:(id)primaryKey;
 
 /**
- Creates a `RLMObject` instance of type `className` in the Realm, and populates it using a given object.
+ Creates an `RLMObject` instance of type `className` in the Realm, and populates it using a given object.
 
  @warning This method is useful only in specialized circumstances, for example, when building components
           that integrate with Realm. If you are simply building an app on Realm, it is recommended to

RealmSwift-swift2.2/Aliases.swift

@@ -42,12 +42,16 @@ import Realm
  * `Data`
  * `Date`
 
- ### Relationships: List (`Array`) and `Object` types
+ ### Relationships: Array (in Swift, `List`) and `Object` types
 
  * `Object`
  * `Array`
 */
 public typealias PropertyType = RLMPropertyType
 
-/// An opaque token which is returned from methods which subscribe to changes to a Realm.
+/**
+ An opaque token which is returned from methods which subscribe to changes to a Realm.
+
+ - see: `addNotificationBlock(_:)`
+ */
 public typealias NotificationToken = RLMNotificationToken

RealmSwift-swift2.2/Error.swift

@@ -23,13 +23,16 @@ import Realm
  `Error` is an enum representing all recoverable errors. It is associated with the
  Realm error domain specified in `RLMErrorDomain`.
 
-    let realm: Realm?
-    do {
-        realm = Realm()
-    } catch RealmSwift.Error.IncompatibleLockFile() {
-        print("Realm Browser app may be attached to Realm on device?")
-    }
-
+ `Error` is a Swift `ErrorType`:
+
+ ```swift
+ let realm: Realm?
+ do {
+     realm = try Realm()
+ } catch RealmSwift.Error.IncompatibleLockFile() {
+     print("Incompatible lock file. The Realm Browser app might be attached to a Realm on the device.")
+ }
+ ```
 */
 public enum Error: ErrorType {
     // swiftlint:disable variable_name

RealmSwift-swift2.2/LinkingObjects.swift

@@ -120,35 +120,27 @@ public final class LinkingObjects<T: Object>: LinkingObjectsBase {
     // MARK: Index Retrieval
 
     /**
-     Returns the index of the given object, or `nil` if the object is not present.
+     Returns the index of an object in the linking objects collection, or `nil` if the object is not present.
 
      - parameter object: The object whose index is being queried.
-
-     - returns: The index of the given object, or `nil` if the object is not present.
      */
     public func indexOf(object: T) -> Int? {
         return notFoundToNil(rlmResults.indexOfObject(unsafeBitCast(object, RLMObject.self)))
     }
 
     /**
-     Returns the index of the first object matching the given predicate,
-     or `nil` if no objects match.
+     Returns the index of the first object matching the given predicate, or `nil` if no objects match.
 
      - parameter predicate: The predicate with which to filter the objects.
-
-     - returns: The index of the first matching object, or `nil` if no objects match.
      */
     public func indexOf(predicate: NSPredicate) -> Int? {
         return notFoundToNil(rlmResults.indexOfObjectWithPredicate(predicate))
     }
 
     /**
-     Returns the index of the first object matching the given predicate,
-     or `nil` if no objects match.
+     Returns the index of the first object matching the given predicate, or `nil` if no objects match.
 
      - parameter predicateFormat: A predicate format string, optionally followed by a variable number of arguments.
-
-     - returns: The index of the first matching object, or `nil` if no objects match.
      */
     public func indexOf(predicateFormat: String, _ args: AnyObject...) -> Int? {
         return notFoundToNil(rlmResults.indexOfObjectWithPredicate(NSPredicate(format: predicateFormat,
@@ -183,9 +175,7 @@ public final class LinkingObjects<T: Object>: LinkingObjectsBase {
      Returns an `Array` containing the results of invoking `valueForKey(_:)` with `key` on each of the linking objects
      collection's objects.
 
-     - parameter key: The name of the property.
-
-     - returns: An `Array` containing the results.
+     - parameter key: The name of the property whose values are desired.
      */
     public override func valueForKey(key: String) -> AnyObject? {
         return rlmResults.valueForKey(key)
@@ -195,9 +185,7 @@ public final class LinkingObjects<T: Object>: LinkingObjectsBase {
      Returns an `Array` containing the results of invoking `valueForKeyPath(_:)` with `keyPath` on each of the linking
      objects collection's objects.
 
-     - parameter keyPath: The key path to the property.
-
-     - returns: An `Array` containing the results.
+     - parameter keyPath: The key path to the property whose values are desired.
      */
     public override func valueForKeyPath(keyPath: String) -> AnyObject? {
         return rlmResults.valueForKeyPath(keyPath)
@@ -209,8 +197,8 @@ public final class LinkingObjects<T: Object>: LinkingObjectsBase {
 
      - warning: This method may only be called during a write transaction.
 
-     - parameter value: The object value.
-     - parameter key:   The name of the property.
+     - parameter value: The value to set the property to.
+     - parameter key:   The name of the property whose value should be set on each object.
      */
     public override func setValue(value: AnyObject?, forKey key: String) {
         return rlmResults.setValue(value, forKey: key)
@@ -219,22 +207,18 @@ public final class LinkingObjects<T: Object>: LinkingObjectsBase {
     // MARK: Filtering
 
     /**
-     Returns all the objects matching the given predicate in the linking objects collection.
+     Returns a `Results` containing all objects matching the given predicate in the linking objects collection.
 
      - parameter predicateFormat: A predicate format string, optionally followed by a variable number of arguments.
-
-     - returns: A `Results` object containing the results.
      */
     public func filter(predicateFormat: String, _ args: AnyObject...) -> Results<T> {
         return Results<T>(rlmResults.objectsWithPredicate(NSPredicate(format: predicateFormat, argumentArray: args)))
     }
 
     /**
-     Returns all the objects matching the given predicate in the linking objects collection.
+     Returns a `Results` containing all objects matching the given predicate in the linking objects collection.
 
      - parameter predicate: The predicate with which to filter the objects.
-
-     - returns: A `Results` object containing the results.
      */
     public func filter(predicate: NSPredicate) -> Results<T> {
         return Results<T>(rlmResults.objectsWithPredicate(predicate))
@@ -243,23 +227,30 @@ public final class LinkingObjects<T: Object>: LinkingObjectsBase {
     // MARK: Sorting
 
     /**
-     Returns a `Results` containing the linking objects collection's elements sorted by the given property name.
+     Returns a `Results` containing the objects in the linking objects collection, but sorted.
 
-     - parameter property:  The property name to sort by.
-     - parameter ascending: The direction to sort in.
+     Objects are sorted based on the values of the given property. For example, to sort a collection of `Student`s from
+     youngest to oldest based on their `age` property, you might call `students.sorted("age", ascending: true)`.
+
+     - warning: Collections may only be sorted by properties of boolean, `NSDate`, single and double-precision floating
+                point, integer, and string types.
 
-     - returns: A `Results` object.
+     - parameter property:  The name of the property to sort by.
+     - parameter ascending: The direction to sort in.
      */
     public func sorted(property: String, ascending: Bool = true) -> Results<T> {
         return sorted([SortDescriptor(property: property, ascending: ascending)])
     }
 
     /**
-     Returns a `Results` containing the linking objects collection's elements sorted by the given sort descriptors.
+     Returns a `Results` containing the objects in the linking objects collection, but sorted.
 
-     - parameter sortDescriptors: A sequence of `SortDescriptor`s to sort by.
+     - warning: Collections may only be sorted by properties of boolean, `NSDate`, single and double-precision floating
+                point, integer, and string types.
 
-     - returns: A `Results` object.
+     - see: `sorted(_:ascending:)`
+
+     - parameter sortDescriptors: A sequence of `SortDescriptor`s to sort by.
      */
     public func sorted<S: SequenceType where S.Generator.Element == SortDescriptor>(sortDescriptors: S) -> Results<T> {
         return Results<T>(rlmResults.sortedResultsUsingDescriptors(sortDescriptors.map { $0.rlmSortDescriptorValue }))
@@ -351,29 +342,31 @@ public final class LinkingObjects<T: Object>: LinkingObjectsBase {
      result, the initial notification will reflect the state of the Realm after
      the write transaction.
 
-         let dog = realm.objects(Dog).first!
-         let owners = dog.owners
-         print("owners.count: \(owners.count)") // => 0
-         let token = owners.addNotificationBlock { (changes: RealmCollectionChange) in
-             switch changes {
-                 case .Initial(let owners):
-                     // Will print "owners.count: 1"
-                     print("owners.count: \(owners.count)")
-                     break
-                 case .Update:
-                     // Will not be hit in this example
-                     break
-                 case .Error:
-                     break
-             }
-         }
-         try! realm.write {
-             realm.add(Person.self, value: ["name": "Mark", dogs: [dog]])
+     ```swift
+     let dog = realm.objects(Dog).first!
+     let owners = dog.owners
+     print("owners.count: \(owners.count)") // => 0
+     let token = owners.addNotificationBlock { changes in
+         switch changes {
+             case .Initial(let owners):
+                 // Will print "owners.count: 1"
+                 print("owners.count: \(owners.count)")
+                 break
+             case .Update:
+                 // Will not be hit in this example
+                 break
+             case .Error:
+                 break
          }
-         // end of runloop execution context
+     }
+     try! realm.write {
+         realm.add(Person.self, value: ["name": "Mark", dogs: [dog]])
+     }
+     // end of runloop execution context
+     ```
 
-     You must retain the returned token for as long as you want updates to continue
-     to be sent to the block. To stop receiving updates, call `stop()` on the token.
+     You must retain the returned token for as long as you want updates to be sent to the block. To stop receiving
+     updates, call `stop()` on the token.
 
      - warning: This method cannot be called during a write transaction, or when
      the containing Realm is read-only.
@@ -392,7 +385,7 @@ public final class LinkingObjects<T: Object>: LinkingObjectsBase {
 extension LinkingObjects: RealmCollectionType {
     // MARK: Sequence Support
 
-    /// Returns a `GeneratorOf<T>` that yields successive elements in the results.
+    /// Returns an `RLMGenerator` that yields successive elements in the results.
     public func generate() -> RLMGenerator<T> {
         return RLMGenerator(collection: rlmResults)
     }