Add documentation for box

Author: nalenz-objectbox

lib/src/box.dart

@@ -45,7 +45,11 @@ class Box<T> {
     }
   }
 
-  // if the respective ID property is given as null or 0, a newly assigned ID is returned, otherwise the existing ID is returned
+  /// Puts the given Object in the box (aka persisting it). If this is a new entity (its ID property is 0), a new ID
+  /// will be assigned to the entity (and returned). If the entity was already put in the box before, it will be
+  /// overwritten.
+  ///
+  /// Performance note: if you want to put several entities, consider [putMany] instead.
   int put(T object, {_PutMode mode = _PutMode.Put}) {
     var propVals = _entityReader(object);
     if (propVals[_modelEntity.idPropName] == null || propVals[_modelEntity.idPropName] == 0) {
@@ -67,7 +71,8 @@ class Box<T> {
     return propVals[_modelEntity.idPropName];
   }
 
-  // only instances whose ID property ot null or 0 will be given a new, valid number for that. A list of the final IDs is returned
+  /// Puts the given [objects] into this Box in a single transaction. Returns a list of all IDs of the inserted
+  /// Objects.
   List<int> putMany(List<T> objects, {_PutMode mode = _PutMode.Put}) {
     if (objects.isEmpty) return [];
 
@@ -129,6 +134,7 @@ class Box<T> {
     return allPropVals.map((p) => p[_modelEntity.idPropName] as int).toList();
   }
 
+  /// Retrieves the stored object with the ID [id] from this box's database. Returns null if not found.
   get(int id) {
     final dataPtrPtr = allocate<Pointer<Uint8>>();
     final sizePtr = allocate<IntPtr>();
@@ -163,7 +169,8 @@ class Box<T> {
     });
   }
 
-  // returns list of ids.length objects of type T, each corresponding to the location of its ID in the ids array. Non-existant IDs become null
+  /// Returns a list of [ids.length] Objects of type T, each corresponding to the location of its ID in [ids].
+  /// Non-existant IDs become null.
   List<T> getMany(List<int> ids) {
     if (ids.isEmpty) return [];
 
@@ -174,14 +181,18 @@ class Box<T> {
             () => checkObxPtr(bindings.obx_box_get_many(_cBox, ptr), "failed to get many objects from box")));
   }
 
+  /// Returns all stored objects in this Box.
   List<T> getAll() {
     const bool allowMissing = false; // throw if null is encountered in the data found
     return _getMany(
         allowMissing, () => checkObxPtr(bindings.obx_box_get_all(_cBox), "failed to get all objects from box"));
   }
 
+  /// Returns a builder to create queries for Object matching supplied criteria.
   QueryBuilder query(Condition qc) => QueryBuilder<T>(_store, _fbManager, _modelEntity.id.id, qc);
 
+  /// Returns the count of all stored Objects in this box or, if [limit] is not zero, the given [limit], whichever
+  /// is lower.
   int count({int limit = 0}) {
     Pointer<Uint64> count = allocate<Uint64>();
     try {
@@ -192,6 +203,7 @@ class Box<T> {
     }
   }
 
+  /// Returns true if no objects are in this box.
   bool isEmpty() {
     Pointer<Uint8> isEmpty = allocate<Uint8>();
     try {
@@ -202,6 +214,7 @@ class Box<T> {
     }
   }
 
+  /// Returns true if this box contains an Object with the ID [id].
   bool contains(int id) {
     Pointer<Uint8> contains = allocate<Uint8>();
     try {
@@ -212,6 +225,7 @@ class Box<T> {
     }
   }
 
+  /// Returns true if this box contains objects with all of the given [ids] using a single transaction.
   bool containsMany(List<int> ids) {
     Pointer<Uint8> contains = allocate<Uint8>();
     try {
@@ -224,13 +238,16 @@ class Box<T> {
     }
   }
 
+  /// Removes (deletes) the Object with the ID [id]. Returns true if an entity was actually removed and false if no
+  /// entity exists with the given ID.
   bool remove(int id) {
     final err = bindings.obx_box_remove(_cBox, id);
     if (err == OBXError.OBX_NOT_FOUND) return false;
     checkObx(err); // throws on other errors
     return true;
   }
 
+  /// Removes (deletes) Objects by their ID in a single transaction. Returns a list of IDs of all removed Objects.
   int removeMany(List<int> ids) {
     Pointer<Uint64> removedIds = allocate<Uint64>();
     try {
@@ -243,6 +260,7 @@ class Box<T> {
     }
   }
 
+  /// Removes (deletes) ALL Objects in a single transaction.
   int removeAll() {
     Pointer<Uint64> removedItems = allocate<Uint64>();
     try {
@@ -253,5 +271,6 @@ class Box<T> {
     }
   }
 
+  /// The low-level pointer to this box.
   get ptr => _cBox;
 }

lib/src/store.dart

@@ -53,9 +53,9 @@ class Store {
     return _entityDefinitions[T];
   }
 
-  /// Executes a given function inside a transaction
+  /// Executes a given function inside a transaction.
   ///
-  /// Returns type of [fn] if [return] is called in [fn]
+  /// Returns type of [fn] if [return] is called in [fn].
   R runInTransaction<R>(TxMode mode, R Function() fn) {
     bool write = mode == TxMode.Write;
     Pointer<Void> txn = write ? bindings.obx_txn_write(_cStore) : bindings.obx_txn_read(_cStore);