documentation and minor cleanups

Author: Ivan Dlugos

objectbox/lib/internal.dart

@@ -4,7 +4,19 @@ library objectbox_internal;
 
 export 'src/model.dart';
 export 'src/modelinfo/index.dart';
-export 'src/query/query.dart';
+export 'src/query/query.dart'
+// don't export the same things as objectbox.dart to avoid docs conflicts
+    hide
+        Query,
+        QueryBuilder,
+        Order,
+        Condition,
+        PropertyQuery,
+        IntegerPropertyQuery,
+        DoublePropertyQuery,
+        StringPropertyQuery;
 export 'src/relations/info.dart';
-export 'src/relations/to_many.dart';
-export 'src/relations/to_one.dart';
+export 'src/relations/to_many.dart'
+    show InternalToManyAccess, InternalToManyTestAccess;
+export 'src/relations/to_one.dart' show InternalToOneAccess;
+export 'src/sync.dart' show InternaSyncTestAccess;

objectbox/lib/objectbox.dart

@@ -22,5 +22,6 @@ export 'src/query/query.dart'
 export 'src/relations/to_many.dart' show ToMany;
 export 'src/relations/to_one.dart' show ToOne;
 export 'src/store.dart' show Store;
-export 'src/sync.dart';
+export 'src/sync.dart'
+    show Sync, SyncClient, SyncCredentials, SyncRequestUpdatesMode, SyncState;
 export 'src/transaction.dart' show TxMode;

objectbox/lib/src/annotations.dart

@@ -17,6 +17,7 @@ class Entity {
   /// Entity instead of creating a new one.
   final int /*?*/ uid;
 
+  /// Create an Entity annotation.
   const Entity({this.uid});
 }
 
@@ -46,6 +47,7 @@ class Property {
   /// The defaults are e.g. Int -> Int64, double -> Float64, bool -> Bool.
   final PropertyType /*?*/ type;
 
+  /// Create an Property annotation.
   const Property({this.type, this.uid});
 }
 
@@ -105,11 +107,13 @@ enum PropertyType {
 /// Annotation Id can be used to specify an entity ID property if it's named
 /// anything else then "id" (case insensitive).
 class Id {
+  /// Create an Id annotation.
   const Id();
 }
 
 /// Transient annotation marks properties that should not be stored in the DB.
 class Transient {
+  /// Create a Transient annotation.
   const Transient();
 }
 
@@ -128,8 +132,10 @@ class Transient {
 /// Note: indexes are currently not supported for ByteVector, Float or Double
 /// properties.
 class Index {
+  /// Index type.
   final IndexType /*?*/ type;
 
+  /// Create an Index annotaion.
   const Index({this.type});
 }
 
@@ -169,6 +175,7 @@ enum IndexType {
 /// It is supported to explicitly add the [Index] annotation to configure the
 /// index type.
 class Unique {
+  /// Create a Unique annotation.
   const Unique();
 }
 
@@ -201,6 +208,8 @@ class Unique {
 /// }
 /// ```
 class Backlink {
+  /// Target entity to which this backlink points. It's the entity that contains
+  /// a [ToOne] or [ToMany] relation pointing to the current entity.
   final String to;
 
   /// If there are multiple relations pointing to the current entity, specify

objectbox/lib/src/box.dart

@@ -14,9 +14,15 @@ import 'relations/to_one.dart';
 import 'store.dart';
 import 'transaction.dart';
 
+/// Box put (write) mode.
 enum PutMode {
+  /// Insert (if given object's ID is zero) or update an existing object.
   put,
+
+  /// Insert a new object.
   insert,
+
+  /// Update an existing object, fails if the given ID doesn't exist.
   update,
 }
 
@@ -37,6 +43,7 @@ class Box<T> {
   final bool _hasToManyRelations;
   final _builder = BuilderWithCBuffer();
 
+  /// Create a box for an Entity.
   factory Box(Store store) => store.box();
 
   Box._(this._store, this._entity)
@@ -305,11 +312,14 @@ class Box<T> {
   }
 }
 
+/// Internal only.
 // TODO enable annotation once meta:1.3.0 is out
 // @internal
 class InternalBoxAccess {
+  /// Create a box in the store for the given entity.
   static Box<T> create<T>(Store store, EntityDefinition<T> entity) =>
       Box._(store, entity);
 
+  /// Close the box, freeing resources.
   static void close(Box box) => box._builder.clear();
 }

objectbox/lib/src/common.dart

@@ -7,10 +7,16 @@ import 'bindings/bindings.dart';
 // TODO use pub_semver?
 /// Wrapper for a semantic version information.
 class Version {
+  /// Major version number.
   final int major;
+
+  /// Minor version number.
   final int minor;
+
+  /// Patch version number.
   final int patch;
 
+  /// Create a version identifier.
   const Version(this.major, this.minor, this.patch);
 
   @override
@@ -35,10 +41,16 @@ Version nativeLibraryVersion() {
 
 /// ObjectBox native exception wrapper.
 class ObjectBoxException implements Exception {
+  /// Dart message related to this native error.
   final String /*?*/ dartMsg;
+
+  /// Native error code.
   final int nativeCode;
+
+  /// Native error message.
   final String /*?*/ nativeMsg;
 
+  /// Create a native exception.
   ObjectBoxException({this.dartMsg, this.nativeCode = 0, this.nativeMsg});
 
   @override

objectbox/lib/src/observable.dart

@@ -79,6 +79,8 @@ extension Streamable<T> on Query<T> {
     };
   }
 
+  /// Create a stream, executing [Query.find()] whenever there's a change to the
+  /// underlying Entity.
   Stream<List<T>> findStream(
       {@Deprecated('Use offset() instead') int offset = 0,
       @Deprecated('Use limit() instead') int limit = 0}) {

objectbox/lib/src/query/builder.dart

@@ -1,11 +1,14 @@
 part of query;
 
-// Construct a tree from the first condition object
+/// Query builder allows creating reusable queries.
 class QueryBuilder<T> extends _QueryBuilder<T> {
+  /// Start creating a query.
   QueryBuilder(Store store, EntityDefinition<T> entity, Condition /*?*/ qc)
       : super(
             store, entity, qc, C.query_builder(store.ptr, entity.model.id.id));
 
+  /// Finish building a [Query]. Call [Query.close()] after you're done with it
+  /// to free resources.
   Query<T> build() {
     _applyCondition();
 
@@ -16,6 +19,8 @@ class QueryBuilder<T> extends _QueryBuilder<T> {
     }
   }
 
+  /// Configure how the results are ordered.
+  /// Pass a combination of [Order] flags.
   QueryBuilder<T> order(QueryProperty p, {int flags = 0}) {
     _throwIfOtherEntity(p._entityId);
     checkObx(C.qb_order(_cBuilder, p._propertyId, flags));

objectbox/lib/src/query/property.dart

@@ -1,11 +1,12 @@
 part of query;
 
+/// Property query base
 abstract class PropertyQuery<T> {
   final Pointer<OBX_query_prop> _cProp;
   final int _type;
   bool _distinct = false;
 
-  PropertyQuery(Pointer<OBX_query> cQuery, int propertyId, this._type)
+  PropertyQuery._(Pointer<OBX_query> cQuery, int propertyId, this._type)
       : _cProp =
             checkObxPtr(C.query_prop(cQuery, propertyId), 'property query');
 
@@ -15,10 +16,12 @@ abstract class PropertyQuery<T> {
   /// Set [replaceNullWith] to return null values as that value.
   List<T> find({T /*?*/ replaceNullWith});
 
+  /// Close the property query, freeing its resources
   void close() {
     checkObx(C.query_prop_close(_cProp));
   }
 
+  /// Get the status of "distinct-values" configuration.
   bool get distinct => _distinct;
 
   /// Set to only return distinct values.
@@ -62,6 +65,7 @@ abstract class PropertyQuery<T> {
 
 /// shared implementation, hence mixin
 mixin _CommonNumeric<T> on PropertyQuery<T> {
+  /// Average value of the property over all objects matching the query.
   double average() {
     final ptr = allocate<Double>();
     try {
@@ -73,9 +77,10 @@ mixin _CommonNumeric<T> on PropertyQuery<T> {
   }
 }
 
+/// "Property query" for an integer field. Created by [Query.property()].
 class IntegerPropertyQuery extends PropertyQuery<int> with _CommonNumeric {
-  IntegerPropertyQuery(Pointer<OBX_query> query, int propertyId, int obxType)
-      : super(query, propertyId, obxType);
+  IntegerPropertyQuery._(Pointer<OBX_query> query, int propertyId, int obxType)
+      : super._(query, propertyId, obxType);
 
   int _op(
       int Function(Pointer<OBX_query_prop>, Pointer<Int64>, Pointer<Int64>)
@@ -89,10 +94,13 @@ class IntegerPropertyQuery extends PropertyQuery<int> with _CommonNumeric {
     }
   }
 
+  /// Minimum value of the property over all objects matching the query.
   int min() => _op(C.query_prop_min_int);
 
+  /// Maximum value of the property over all objects matching the query.
   int max() => _op(C.query_prop_max_int);
 
+  /// Sum of all property values over objects matching the query.
   int sum() => _op(C.query_prop_sum_int);
 
   @override
@@ -143,9 +151,10 @@ class IntegerPropertyQuery extends PropertyQuery<int> with _CommonNumeric {
   }
 }
 
+/// "Property query" for a double field. Created by [Query.property()].
 class DoublePropertyQuery extends PropertyQuery<double> with _CommonNumeric {
-  DoublePropertyQuery(Pointer<OBX_query> query, int propertyId, int obxType)
-      : super(query, propertyId, obxType);
+  DoublePropertyQuery._(Pointer<OBX_query> query, int propertyId, int obxType)
+      : super._(query, propertyId, obxType);
 
   double _op(
       int Function(Pointer<OBX_query_prop>, Pointer<Double>, Pointer<Int64>)
@@ -159,10 +168,13 @@ class DoublePropertyQuery extends PropertyQuery<double> with _CommonNumeric {
     }
   }
 
+  /// Minimum value of the property over all objects matching the query.
   double min() => _op(C.query_prop_min);
 
+  /// Maximum value of the property over all objects matching the query.
   double max() => _op(C.query_prop_max);
 
+  /// Sum of all property values over objects matching the query.
   double sum() => _op(C.query_prop_sum);
 
   @override
@@ -193,11 +205,12 @@ class DoublePropertyQuery extends PropertyQuery<double> with _CommonNumeric {
   }
 }
 
+/// "Property query" for a string field. Created by [Query.property()].
 class StringPropertyQuery extends PropertyQuery<String> {
   bool _caseSensitive = false;
 
-  StringPropertyQuery(Pointer<OBX_query> query, int propertyId, int obxType)
-      : super(query, propertyId, obxType);
+  StringPropertyQuery._(Pointer<OBX_query> query, int propertyId, int obxType)
+      : super._(query, propertyId, obxType);
 
   /// Set to return case sensitive distinct values.
   ///
@@ -207,6 +220,7 @@ class StringPropertyQuery extends PropertyQuery<String> {
     checkObx(C.query_prop_distinct_case(_cProp, _distinct, _caseSensitive));
   }
 
+  /// Get status of the case-sensitive configuration.
   bool get caseSensitive => _caseSensitive;
 
   @override

objectbox/lib/src/query/query.dart

@@ -15,9 +15,11 @@ import '../store.dart';
 import '../transaction.dart';
 
 part 'builder.dart';
-
 part 'property.dart';
 
+// ignore_for_file: public_member_api_docs
+
+/// Groups query order flags.
 class Order {
   /// Reverts the order from ascending (default) to descending.
   static final descending = 1;
@@ -64,7 +66,7 @@ class QueryStringProperty extends QueryProperty {
       _StringCondition(cop, this, p, null, caseSensitive: caseSensitive);
 
   Condition _opList(List<String> list, _ConditionOp cop,
-      {/*required*/ bool caseSensitive}) =>
+          {/*required*/ bool caseSensitive}) =>
       _StringListCondition(cop, this, list, caseSensitive: caseSensitive);
 
   Condition equals(String p, {bool caseSensitive = false}) =>
@@ -382,7 +384,7 @@ class _StringListCondition extends _PropertyCondition<List<String>> {
   final bool _caseSensitive;
 
   _StringListCondition(_ConditionOp op, QueryProperty prop, List<String> value,
-  {/*required*/ bool caseSensitive})
+      {/*required*/ bool caseSensitive})
       : _caseSensitive = caseSensitive,
         super(op, prop, value);
 
@@ -612,7 +614,7 @@ class _ConditionGroupAll extends _ConditionGroup {
 
 /// A repeatable Query returning the latest matching Objects.
 ///
-/// Use [find] or related methods to fetch the latest results from the BoxStore.
+/// Use [find] or related methods to fetch the latest results from the Box.
 ///
 /// Use [property] to only return values or an aggregate of a single Property.
 class Query<T> {
@@ -755,12 +757,12 @@ class Query<T> {
   /// ```
   PQ property<PQ extends PropertyQuery<dynamic>>(QueryProperty qp) {
     if (OBXPropertyType.Bool <= qp._type && qp._type <= OBXPropertyType.Long) {
-      return IntegerPropertyQuery(_cQuery, qp._propertyId, qp._type) as PQ;
+      return IntegerPropertyQuery._(_cQuery, qp._propertyId, qp._type) as PQ;
     } else if (OBXPropertyType.Float == qp._type ||
         qp._type == OBXPropertyType.Double) {
-      return DoublePropertyQuery(_cQuery, qp._propertyId, qp._type) as PQ;
+      return DoublePropertyQuery._(_cQuery, qp._propertyId, qp._type) as PQ;
     } else if (OBXPropertyType.String == qp._type) {
-      return StringPropertyQuery(_cQuery, qp._propertyId, qp._type) as PQ;
+      return StringPropertyQuery._(_cQuery, qp._propertyId, qp._type) as PQ;
     } else {
       throw Exception(
           'Property query: unsupported type (OBXPropertyType: ${qp._type})');