ToOne/ToMany: improve class descriptions, notable things first

Author: greenrobot-team

objectbox/lib/src/relations/to_many.dart

@@ -8,48 +8,43 @@ import '../store.dart';
 import '../transaction.dart';
 import 'info.dart';
 
-/// A lazily loaded `List` of target objects representing a to-many relation,
-/// a unidirectional link from a "source" entity to multiple objects of a
-/// "target" entity.
-///
-/// It tracks changes (adds and removes) that can be later applied (persisted)
-/// to the database. This happens either when the source entity of this relation
-/// is put or using [applyToDb]. For some important details about applying
-/// changes, see the notes about relations of [Box.put].
-///
-/// The objects are loaded lazily on first access of this list, and then cached.
-/// Subsequent calls to any method, like [length], do not query the database,
-/// even if the relation was changed elsewhere. To get the latest data [Box.get]
-/// the source object again.
-///
-/// You can:
-///   - [add] new objects to the relation.
-///   - [removeAt] target objects from the relation at a specific list index.
-///   - [remove] target objects from the relation by an ID.
+/// A to-many relation of an entity that references multiple objects of a "target" entity [EntityT].
 ///
+/// Example:
 /// ```
+/// @Entity()
 /// class Student {
 ///   final teachers = ToMany<Teacher>();
 /// }
+/// ```
 ///
-/// // Example 1: create a relation
-/// final teacher1 = Teacher();
-/// final teacher2 = Teacher();
+/// Implements the `List` interface and uses lazy initialization.
+/// The target objects are only read from the database when the list is first accessed.
 ///
-/// final student1 = Student();
-/// student1.teachers.add(teacher1);
-/// student1.teachers.add(teacher2);
+/// Tracks when target objects are added and removed. Common usage:
+///   - [add] target objects to the relation.
+///   - [remove] target objects from the relation.
+///   - [removeAt] target objects at a specific index.
 ///
-/// final student2 = Student();
-/// student2.teachers.add(teacher2);
+/// To apply (persist) the changes to the database, call [applyToDb] or put the object with the ToMany.
+/// For important details, see the notes about relations of [Box.put].
 ///
-/// // saves students as well as teachers in the database
-/// store.box<Student>().putMany([student1, student2]);
+/// ```
+/// // Example 1: add target objects to a relation
+/// student.teachers.add(teacher1);
+/// student.teachers.add(teacher2);
+/// store.box<Student>().put(student);
 ///
-/// // Example 2: remove a relation
-/// student.teachers.removeAt(index)
-/// student.teachers.applyToDb(); // or store.box<Student>().put(student);
+/// // Example 2: remove a target object from the relation
+/// student.teachers.removeAt(index);
+/// student.teachers.applyToDb();
+/// // or store.box<Student>().put(student);
 /// ```
+///
+/// In the database, the target objects are referenced by their IDs, which are
+/// persisted as part of the relation of the object with the ToMany.
+///
+/// To get all objects with a ToMany that reference a target object, see [Backlink].
 class ToMany<EntityT> extends Object with ListMixin<EntityT> {
   /// Store-related configuration attached to this.
   ///

objectbox/lib/src/relations/to_one.dart

@@ -1,49 +1,48 @@
+import '../annotations.dart';
 import '../box.dart';
 import '../modelinfo/entity_definition.dart';
 import '../native/transaction.dart';
 import '../store.dart';
 
-/// Manages a to-one relation, an unidirectional link from a "source" entity to
-/// a "target" entity. The target object is referenced by its ID, which is
-/// persisted in the source object.
-///
-/// You can:
-///   - set [target]=null or [targetId]=0 to remove the relation.
-///   - set [target] to an object to set the relation.
-///     Call [Box<SourceEntity>.put()] to persist the changes. If the target
-///     object is a new one (its ID is 0), it will be also saved automatically.
-///   - set [targetId] to an existing object's ID to set the relation.
-///     Call [Box<SourceEntity>.put()] to persist the changes.
+/// A to-one relation of an entity that references one object of a "target" entity [EntityT].
 ///
+/// Example:
 /// ```
 /// @Entity()
 /// class Order {
 ///   final customer = ToOne<Customer>();
-///   ...
 /// }
+/// ```
 ///
-/// // Example 1: create a relation
-/// final order = Order(...);
-/// final customer = Customer();
-/// order.customer.target = customer;
+/// Uses lazy initialization.
+/// The [target] object is only read from the database when it is first accessed.
 ///
-/// // Or you could create the target object in place:
-/// // order.customer.target = Customer()
+/// Common usage:
+///   - set the [target] object to create a relation.
+///     When the object with the ToOne is put, if the target object is new (its ID is 0), it will be put as well.
+///     Otherwise, only the target ID in the database is updated.
+///   - set the [targetId] of the target object to create a relation.
+///   - set [target] to `null` or [targetId] to `0` to remove the relation.
 ///
-/// // attach() must be called when creating new instances. On objects (e.g.
-/// // "orders" in this example) read with box.get() its done automatically.
-/// order.customer.attach(store);
+/// Then, to persist the changes [Box.put] the object with the ToOne.
 ///
-/// // saves both [customer] and [order] in the database
+/// ```
+/// // Example 1: create a relation
+/// order.customer.target = customer;
+/// // or order.customer.targetId = customerId;
 /// store.box<Order>().put(order);
 ///
-///
-/// // Example 2: remove a relation
-///
+/// // Example 2: remove the relation
 /// order.customer.target = null
-/// // ... or ...
-/// order.customer.targetId = 0
+/// // or order.customer.targetId = 0
+/// store.box<Order>().put(order);
 /// ```
+///
+/// The target object is referenced by its ID.
+/// This [targetId] is persisted as part of the object with the ToOne in a special
+/// property created for each ToOne (named like "customerId").
+///
+/// To get all objects with a ToOne that reference a target object, see [Backlink].
 class ToOne<EntityT> {
   /// Store-related configuration attached to this.
   ///