Document all public moor apis, enable appropriate lint

CONTRIBUTING.md

@@ -108,6 +108,9 @@ updates that span multiple versions, we should follow these steps
  
 The `sqlparser` library can be published independently from moor.
 
+Significant updates to more than one package, or updates to the `moor` package, should get
+their own tag in git!
+
 ### Building the documentation
 We use hugo and docsy to build the documentation. The [readme](docs/README.md) contains everything
 you need to know go get started.

analysis_options.yaml

@@ -7,6 +7,7 @@ analyzer:
     unused_local_variable: error
     dead_code: error
     override_on_non_overriding_method: error
+    public_member_api_docs: ignore # turned on by user-facing subpackages
   exclude:
     - "**/*.g.dart"
     # Will be analyzed anyway, nobody knows why ¯\_(ツ)_/¯. We're only analyzing lib/ and test/ as a workaround
@@ -81,4 +82,5 @@ linter:
     - unnecessary_this
     - unrelated_type_equality_checks
     - use_rethrow_when_possible
-    - valid_regexps
+    - valid_regexps
+    - public_member_api_docs

moor/analysis_options.yaml

@@ -1 +0,0 @@
-../analysis_options.yaml

moor/analysis_options.yaml

@@ -0,0 +1,8 @@
+include: ../analysis_options.yaml
+
+analyzer:
+  errors:
+    public_member_api_docs: warning
+  exclude:
+    - "example_web/**"
+    - "example/**"

moor/lib/sqlite_keywords.dart

@@ -1,7 +1,9 @@
 /// Provides utilities around sql keywords, like optional escaping etc.
 library moor.sqlite_keywords;
 
-// https://www.sqlite.org/lang_keywords.html
+/// Contains a set of all sqlite keywords, according to
+/// https://www.sqlite.org/lang_keywords.html. Moor will use this list to
+/// escape keywords.
 const sqliteKeywords = {
   'ABORT',
   'ACTION',
@@ -141,8 +143,11 @@ const sqliteKeywords = {
   'WITHOUT'
 };
 
+/// Returns whether [s] is an sql keyword by comparing it to the
+/// [sqliteKeywords].
 bool isSqliteKeyword(String s) => sqliteKeywords.contains(s.toUpperCase());
 
+/// Escapes [s] by wrapping it in backticks if it's an sqlite keyword.
 String escapeIfNeeded(String s) {
   if (isSqliteKeyword(s)) return '`$s`';
   return s;

moor/lib/src/dsl/columns.dart

@@ -3,8 +3,11 @@ import 'dart:typed_data';
 import 'package:moor/moor.dart';
 import 'package:moor/src/runtime/expressions/expression.dart';
 
+/// Base class for columns in sql. The [T] type refers to the type a value of
+/// this column will have in Dart, [S] is the mapping class from moor.
 abstract class Column<T, S extends SqlType<T>> extends Expression<T, S> {}
 
+/// A column that stores int values.
 abstract class IntColumn extends Column<int, IntType> implements IntExpression {
 }
 
@@ -155,6 +158,8 @@ class ColumnBuilder<
   ResultColumn call() => null;
 }
 
+/// Tells the generator to build an [IntColumn]. See the docs at [ColumnBuilder]
+/// for details.
 class IntColumnBuilder
     extends ColumnBuilder<IntColumnBuilder, IntColumn, IntType, int> {
   /// Enables auto-increment for this column, which will also make this column
@@ -162,15 +167,23 @@ class IntColumnBuilder
   IntColumnBuilder autoIncrement() => this;
 }
 
+/// Tells the generator to build an [BoolColumn]. See the docs at
+/// [ColumnBuilder] for details.
 class BoolColumnBuilder
     extends ColumnBuilder<BoolColumnBuilder, BoolColumn, BoolType, bool> {}
 
+/// Tells the generator to build an [BlobColumn]. See the docs at
+/// [ColumnBuilder] for details.
 class BlobColumnBuilder
     extends ColumnBuilder<BlobColumnBuilder, BlobColumn, BlobType, Uint8List> {}
 
+/// Tells the generator to build an [RealColumn]. See the docs at
+/// [ColumnBuilder] for details.
 class RealColumnBuilder
     extends ColumnBuilder<RealColumnBuilder, RealColumn, RealType, num> {}
 
+/// Tells the generator to build an [TextColumn]. See the docs at
+/// [ColumnBuilder] for details.
 class TextColumnBuilder
     extends ColumnBuilder<TextColumnBuilder, TextColumn, StringType, String> {
   /// Puts a constraint on the minimum and maximum length of text that can be
@@ -182,6 +195,8 @@ class TextColumnBuilder
   TextColumnBuilder withLength({int min, int max}) => this;
 }
 
+/// Tells the generator to build an [DateTimeColumn]. See the docs at
+/// [ColumnBuilder] for details.
 class DateTimeColumnBuilder extends ColumnBuilder<DateTimeColumnBuilder,
     DateTimeColumn, DateTimeType, DateTime> {}
 

moor/lib/src/dsl/database.dart

@@ -96,6 +96,8 @@ class UseDao {
   @experimental
   final Set<String> include;
 
+  /// Annotation for a class to declare it as an dao. See [UseDao] and the
+  /// referenced documentation on how to use daos with moor.
   const UseDao(
       {@required this.tables,
       this.queries = const {},

moor/lib/src/dsl/table.dart

@@ -117,6 +117,8 @@ abstract class Table {
 /// used.
 /// {@template}
 class DataClassName {
+  /// The overridden name to use when generating the data class for a table.
+  /// {@macro moor:custom_data_class}
   final String name;
 
   /// Customize the data class name for a given table.

moor/lib/src/runtime/components/component.dart

@@ -13,7 +13,14 @@ abstract class Component {
 /// An enumeration of database systems supported by moor. Only
 /// [SqlDialect.sqlite] is officially supported, all others are in an
 /// experimental state at the moment.
-enum SqlDialect { sqlite, mysql }
+enum SqlDialect {
+  /// Use sqlite's sql dialect. This is the default option and the only
+  /// officially supported dialect at the moment.
+  sqlite,
+
+  /// (currently unsupported)
+  mysql
+}
 
 /// Contains information about a query while it's being constructed.
 class GenerationContext {
@@ -23,8 +30,14 @@ class GenerationContext {
   /// queries.
   bool hasMultipleTables = false;
 
+  /// The [SqlTypeSystem] to use when mapping variables to values that the
+  /// underlying database understands.
   final SqlTypeSystem typeSystem;
+
+  /// The [SqlDialect] that should be respected when generating the query.
   final SqlDialect dialect;
+
+  /// The actual [QueryExecutor] that's going to execute the generated query.
   final QueryExecutor executor;
 
   final List<dynamic> _boundVariables = [];
@@ -36,6 +49,8 @@ class GenerationContext {
   /// All variables ("?" in sql) that were added to this context.
   final List<Variable> introducedVariables = [];
 
+  /// Returns the amount of variables that have been introduced when writing
+  /// this query.
   int get amountOfVariables => boundVariables.length;
 
   /// The string buffer contains the sql query as it's being constructed.
@@ -44,11 +59,15 @@ class GenerationContext {
   /// Gets the generated sql statement
   String get sql => buffer.toString();
 
+  /// Constructs a [GenerationContext] by copying the relevant fields from the
+  /// database.
   GenerationContext.fromDb(QueryEngine database)
       : typeSystem = database.typeSystem,
         executor = database.executor,
         dialect = database.executor?.dialect ?? SqlDialect.sqlite;
 
+  /// Constructs a custom [GenerationContext] by setting the fields manually.
+  /// See [GenerationContext.fromDb] for a more convenient factory.
   GenerationContext(this.typeSystem, this.executor,
       {this.dialect = SqlDialect.sqlite});
 

moor/lib/src/runtime/components/join.dart

@@ -2,7 +2,17 @@ import 'package:moor/moor.dart';
 import 'package:moor/src/runtime/components/component.dart';
 import 'package:moor/src/runtime/expressions/expression.dart';
 
-enum JoinType { inner, leftOuter, cross }
+/// A type for a [Join] (e.g. inner, outer).
+enum JoinType {
+  /// Perform an inner join, see the [innerJoin] function for details.
+  inner,
+
+  /// Perform a (left) outer join, see also [leftOuterJoin]
+  leftOuter,
+
+  /// Perform a full cross join, see also [crossJoin].
+  cross
+}
 
 const Map<JoinType, String> _joinKeywords = {
   JoinType.inner: 'INNER',
@@ -10,11 +20,20 @@ const Map<JoinType, String> _joinKeywords = {
   JoinType.cross: 'CROSS',
 };
 
+/// Used internally by moor when calling [SimpleSelectStatement.join].
 class Join<T extends Table, D extends DataClass> extends Component {
+  /// The [JoinType] of this join.
   final JoinType type;
+
+  /// The [TableInfo] that will be added to the query
   final TableInfo<T, D> table;
+
+  /// For joins that aren't [JoinType.cross], contains an additional predicate
+  /// that must be matched for the join.
   final Expression<bool, BoolType> on;
 
+  /// Constructs a [Join] by providing the relevant fields. [on] is optional for
+  /// [JoinType.cross].
   Join(this.type, this.table, this.on);
 
   @override

moor/lib/src/runtime/components/limit.dart

@@ -9,6 +9,8 @@ class Limit extends Component {
   /// included in the result.
   final int offset;
 
+  /// Construct a limit clause from the [amount] of rows to include an a
+  /// nullable [offset].
   Limit(this.amount, this.offset);
 
   @override

moor/lib/src/runtime/components/order_by.dart

@@ -2,6 +2,7 @@ import 'package:meta/meta.dart';
 import 'package:moor/src/runtime/components/component.dart';
 import 'package:moor/src/runtime/expressions/expression.dart';
 
+/// Describes how to order rows
 enum OrderingMode {
   /// Ascending ordering mode (lowest items first)
   asc,
@@ -24,6 +25,8 @@ class OrderingTerm extends Component {
   /// The ordering mode (ascending or descending).
   final OrderingMode mode;
 
+  /// Creates an ordering term by the [expression] and the [mode] (defaults to
+  /// ascending).
   OrderingTerm({@required this.expression, this.mode = OrderingMode.asc});
 
   @override
@@ -39,8 +42,12 @@ class OrderingTerm extends Component {
 /// the later terms only being considered if the first term considers two rows
 /// equal.
 class OrderBy extends Component {
+  /// The list of ordering terms to respect. Terms appearing earlier in this
+  /// list are more important, the others will only considered when two rows
+  /// are equal by the first [OrderingTerm].
   final List<OrderingTerm> terms;
 
+  /// Constructs an order by clause by the [terms].
   OrderBy(this.terms);
 
   @override

moor/lib/src/runtime/components/where.dart

@@ -8,6 +8,7 @@ class Where extends Component {
   /// the result.
   final Expression<bool, BoolType> predicate;
 
+  /// Construct a [Where] clause from its [predicate].
   Where(this.predicate);
 
   @override

moor/lib/src/runtime/data_class.dart

@@ -14,6 +14,7 @@ abstract class Insertable<D extends DataClass> {
 /// A common supertype for all data classes generated by moor. Data classes are
 /// immutable structures that represent a single row in a database table.
 abstract class DataClass {
+  /// Constant constructor so that generated data classes can be constant.
   const DataClass();
 
   /// Converts this object into a representation that can be encoded with
@@ -43,6 +44,7 @@ abstract class DataClass {
 /// - the explanation in the changelog for 1.5
 /// - https://github.com/simolus3/moor/issues/25
 abstract class UpdateCompanion<D extends DataClass> implements Insertable<D> {
+  /// Constant constructor so that generated companion classes can be constant.
   const UpdateCompanion();
 
   @override
@@ -52,12 +54,21 @@ abstract class UpdateCompanion<D extends DataClass> implements Insertable<D> {
 }
 
 /// A wrapper around arbitrary data [T] to indicate presence or absence
-/// explicitly.
+/// explicitly. We can use [Value]s in companions to distinguish between null
+/// and absent values.
 class Value<T> {
+  /// Whether this [Value] wrapper contains a present [value] that should be
+  /// inserted or updated.
   final bool present;
+
+  /// If this value is [present], contains the value to update or insert.
   final T value;
 
+  /// Create a (present) value by wrapping the [value] provided.
   const Value(this.value) : present = true;
+
+  /// Create an absent value that will not be written into the database, the
+  /// default value or null will be used instead.
   const Value.absent()
       : value = null,
         present = false;
@@ -65,6 +76,7 @@ class Value<T> {
 
 /// Serializer responsible for mapping atomic types from and to json.
 abstract class ValueSerializer {
+  /// Constant super-constructor to allow constant child classes.
   const ValueSerializer();
 
   /// The default serializer encodes date times as a unix-timestamp in

moor/lib/src/runtime/database.dart

@@ -26,9 +26,11 @@ abstract class DatabaseAccessor<T extends GeneratedDatabase>
   @override
   final bool topLevel = true;
 
+  /// The main database instance for this dao
   @protected
   final T db;
 
+  /// Used internally by moor
   DatabaseAccessor(this.db) : super.delegate(db);
 }
 
@@ -47,10 +49,14 @@ abstract class DatabaseConnectionUser {
   @protected
   StreamQueryStore streamQueries;
 
+  /// Constructs a database connection user, which is responsible to store query
+  /// streams, wrap the underlying executor and perform type mapping.
   DatabaseConnectionUser(this.typeSystem, this.executor, {this.streamQueries}) {
     streamQueries ??= StreamQueryStore();
   }
 
+  /// Creates another [DatabaseConnectionUser] by referencing the implementation
+  /// from the [other] user.
   DatabaseConnectionUser.delegate(DatabaseConnectionUser other,
       {SqlTypeSystem typeSystem,
       QueryExecutor executor,
@@ -360,6 +366,7 @@ abstract class GeneratedDatabase extends DatabaseConnectionUser
   /// A list of tables specified in this database.
   List<TableInfo> get allTables;
 
+  /// Used by generated code
   GeneratedDatabase(SqlTypeSystem types, QueryExecutor executor,
       {StreamQueryStore streamStore})
       : super(types, executor, streamQueries: streamStore) {

moor/lib/src/runtime/exceptions.dart

@@ -1,7 +1,9 @@
 /// Thrown when one attempts to insert or update invalid data into a table.
 class InvalidDataException implements Exception {
+  /// A message explaining why the data couldn't be inserted into the database.
   final String message;
 
+  /// Construct a new [InvalidDataException] from the [message].
   InvalidDataException(this.message);
 
   @override
@@ -16,10 +18,18 @@ class InvalidDataException implements Exception {
 /// For instance, when we know that an invalid statement has been constructed,
 /// we catch the database exception and try to explain why that has happened.
 class MoorWrappedException implements Exception {
+  /// Contains a possible description of why the underlying [cause] occurred,
+  /// for instance because a moor api was misused.
   final String message;
+
+  /// The underlying exception caught by moor
   final dynamic cause;
+
+  /// The original stacktrace when caught by moor
   final StackTrace trace;
 
+  /// Creates a new [MoorWrappedException] to provide additional details about
+  /// an underlying error from the database.
   MoorWrappedException({this.message, this.cause, this.trace});
 
   @override

moor/lib/src/runtime/executor/before_open.dart

@@ -4,6 +4,7 @@ import 'package:moor/src/runtime/executor/stream_queries.dart';
 
 /// Used internally by moor.
 class BeforeOpenEngine extends DatabaseConnectionUser with QueryEngine {
+  /// Used internally by moor.
   BeforeOpenEngine(DatabaseConnectionUser other, QueryExecutor executor)
       : super.delegate(
           other,

moor/lib/src/runtime/executor/executor.dart

@@ -15,6 +15,9 @@ import 'package:moor/src/utils/hash.dart';
 /// engine to use with moor and run into issues, please consider creating an
 /// issue.
 abstract class QueryExecutor {
+  /// The higher-level database class attached to this executor. This
+  /// information can be used to read the [GeneratedDatabase.schemaVersion] when
+  /// opening the database.
   GeneratedDatabase databaseInfo;
 
   /// The [SqlDialect] to use for this database engine.
@@ -75,6 +78,7 @@ class BatchedStatement {
   /// variables that should be bound to the [sql] statement.
   final List<List<dynamic>> variables;
 
+  /// Constructs a batched statement from the [sql] and the set of [variables].
   BatchedStatement(this.sql, this.variables);
 
   @override

moor/lib/src/runtime/executor/helpers/delegates.dart

@@ -109,6 +109,7 @@ abstract class QueryDelegate {
 ///
 /// Clients may not extend, implement or mix-in this class directly.
 abstract class TransactionDelegate {
+  /// Const constructor on superclass
   const TransactionDelegate();
 }
 
@@ -127,6 +128,9 @@ class NoTransactionDelegate extends TransactionDelegate {
   /// database engine.
   final String rollback;
 
+  /// Construct a transaction delegate indicating that native transactions
+  /// aren't supported and need to be emulated by issuing statements and
+  /// locking the database.
   const NoTransactionDelegate({
     this.start = 'BEGIN TRANSACTION',
     this.commit = 'COMMIT TRANSACTION',
@@ -137,6 +141,7 @@ class NoTransactionDelegate extends TransactionDelegate {
 /// A [TransactionDelegate] for database APIs which do support creating and
 /// managing transactions themselves.
 abstract class SupportedTransactionDelegate extends TransactionDelegate {
+  /// Constant constructor on superclass
   const SupportedTransactionDelegate();
 
   /// Start a transaction, which we assume implements [QueryEngine], and call
@@ -150,11 +155,14 @@ abstract class SupportedTransactionDelegate extends TransactionDelegate {
 ///
 /// Clients may not extend, implement or mix-in this class directly.
 abstract class DbVersionDelegate {
+  /// Constant constructor on superclass
   const DbVersionDelegate();
 }
 
 /// A database that doesn't support setting schema versions.
 class NoVersionDelegate extends DbVersionDelegate {
+  /// Delegate indicating that the underlying database does not support schema
+  /// versions.
   const NoVersionDelegate();
 }
 
@@ -163,11 +171,13 @@ class OnOpenVersionDelegate extends DbVersionDelegate {
   /// Function that returns with the current schema version.
   final Future<int> Function() loadSchemaVersion;
 
+  /// See [OnOpenVersionDelegate].
   const OnOpenVersionDelegate(this.loadSchemaVersion);
 }
 
 /// A database that supports setting the schema version at any time.
 abstract class DynamicVersionDelegate extends DbVersionDelegate {
+  /// See [DynamicVersionDelegate]
   const DynamicVersionDelegate();
 
   /// Load the current schema version stored in this database.

moor/lib/src/runtime/executor/helpers/engines.dart

@@ -220,6 +220,7 @@ class _BeforeOpeningExecutor extends QueryExecutor
 /// A database engine (implements [QueryExecutor]) that delegated the relevant
 /// work to a [DatabaseDelegate].
 class DelegatedDatabase extends QueryExecutor with _ExecutorWithQueryDelegate {
+  /// The [DatabaseDelegate] to send queries to.
   final DatabaseDelegate delegate;
 
   @override
@@ -235,6 +236,7 @@ class DelegatedDatabase extends QueryExecutor with _ExecutorWithQueryDelegate {
 
   final Lock _openingLock = Lock();
 
+  /// Constructs a delegated database by providing the [delegate].
   DelegatedDatabase(this.delegate,
       {this.logStatements, this.isSequential = false}) {
     // not using default value because it's commonly set to null

moor/lib/src/runtime/executor/helpers/results.dart

@@ -9,12 +9,16 @@ class QueryResult {
 
   Map<String, int> _columnIndexes;
 
+  /// Constructs a [QueryResult] by specifying the order of column names in
+  /// [columnNames] and the associated data in [rows].
   QueryResult(this.columnNames, this.rows) {
     _columnIndexes = {
       for (var column in columnNames) column: columnNames.lastIndexOf(column)
     };
   }
 
+  /// Converts the [rows] into [columnNames] and raw data [QueryResult.rows].
+  /// We assume that each map in [rows] has the same keys.
   factory QueryResult.fromRows(List<Map<String, dynamic>> rows) {
     if (rows.isEmpty) {
       return QueryResult(const [], const []);

moor/lib/src/runtime/executor/stream_queries.dart

@@ -7,6 +7,9 @@ import 'package:moor/src/utils/start_with_value_transformer.dart';
 
 const _listEquality = ListEquality<dynamic>();
 
+// This is an internal moor library that's never exported to users.
+// ignore_for_file: public_member_api_docs
+
 /// Representation of a select statement that knows from which tables the
 /// statement is reading its data and how to execute the query.
 class QueryStreamFetcher<T> {

moor/lib/src/runtime/executor/transactions.dart

@@ -1,7 +1,10 @@
 import 'package:moor/moor.dart';
 import 'package:moor/src/runtime/executor/stream_queries.dart';
 
+/// Runs multiple statements transactionally.
 class Transaction extends DatabaseConnectionUser with QueryEngine {
+  /// Constructs a transaction executor from the [other] user and the underlying
+  /// [executor].
   Transaction(DatabaseConnectionUser other, TransactionExecutor executor)
       : super.delegate(
           other,
@@ -9,6 +12,8 @@ class Transaction extends DatabaseConnectionUser with QueryEngine {
           streamQueries: _TransactionStreamStore(other.streamQueries),
         );
 
+  /// Instructs the underlying executor to execute this instructions. Batched
+  /// table updates will also be send to the stream query store.
   Future complete() async {
     final streams = streamQueries as _TransactionStreamStore;
     await (executor as TransactionExecutor).send();

moor/lib/src/runtime/expressions/comparable.dart

@@ -1,12 +1,20 @@
 import 'package:moor/moor.dart';
 import 'expression.dart';
 
+// todo: Can we replace these classes with an extension on expression?
+
+/// An [Expression] that operates on ints. Declared as a class so that we can
+/// mixin [ComparableExpr].
 abstract class IntExpression extends Expression<int, IntType>
     implements ComparableExpr<int, IntType> {}
 
+/// An [Expression] that operates on doubles. Declared as a class so that we can
+/// mixin [ComparableExpr].
 abstract class DoubleExpression extends Expression<double, RealType>
     implements ComparableExpr<double, RealType> {}
 
+/// An [Expression] that operates on datetimes. Declared as a class so that we
+/// can mixin [ComparableExpr].
 abstract class DateTimeExpression extends Expression<DateTime, DateTimeType>
     implements ComparableExpr<DateTime, DateTimeType> {}
 

moor/lib/src/runtime/expressions/custom.dart

@@ -10,8 +10,10 @@ import 'package:moor/src/runtime/expressions/expression.dart';
 ///  - [currentDate] and [currentDateAndTime], which use a [CustomExpression]
 ///  internally.
 class CustomExpression<D, S extends SqlType<D>> extends Expression<D, S> {
+  /// The SQL of this expression
   final String content;
 
+  /// Constructs a custom expression by providing the raw sql [content].
   const CustomExpression(this.content);
 
   @override

moor/lib/src/runtime/expressions/expression.dart

@@ -7,8 +7,11 @@ import 'package:moor/src/types/sql_types.dart';
 /// include queries (which might evaluate to multiple values) but individual
 /// columns, functions and operators.
 abstract class Expression<D, T extends SqlType<D>> implements Component {
+  /// Constant constructor so that subclasses can be constant.
   const Expression();
 
+  /// Whether this expression is a literal. Some use-sites need to put
+  /// parentheses around non-literals.
   bool get isLiteral => false;
 
   /// Whether this expression is equal to the given expression.
@@ -26,10 +29,17 @@ abstract class Expression<D, T extends SqlType<D>> implements Component {
 /// An expression that looks like "$a operator $b", where $a and $b itself
 /// are expressions and the operator is any string.
 abstract class InfixOperator<D, T extends SqlType<D>> extends Expression<D, T> {
+  /// The left-hand side of this expression
   Expression get left;
+
+  /// The right-hand side of this expresion
   Expression get right;
+
+  /// The sql operator to write
   String get operator;
 
+  /// Whether we should put parentheses around the [left] and [right]
+  /// expressions.
   @visibleForOverriding
   bool get placeBrackets => true;
 
@@ -55,11 +65,27 @@ abstract class InfixOperator<D, T extends SqlType<D>> extends Expression<D, T> {
   }
 }
 
-enum ComparisonOperator { less, lessOrEqual, equal, moreOrEqual, more }
+/// Defines the possible comparison operators that can appear in a [Comparison].
+enum ComparisonOperator {
+  /// '<' in sql
+  less,
+
+  /// '<=' in sql
+  lessOrEqual,
+
+  /// '=' in sql
+  equal,
+
+  /// '>=' in sql
+  moreOrEqual,
+
+  /// '>' in sql
+  more
+}
 
 /// An expression that compares two child expressions.
 class Comparison extends InfixOperator<bool, BoolType> {
-  static const Map<ComparisonOperator, String> operatorNames = {
+  static const Map<ComparisonOperator, String> _operatorNames = {
     ComparisonOperator.less: '<',
     ComparisonOperator.lessOrEqual: '<=',
     ComparisonOperator.equal: '=',
@@ -71,15 +97,20 @@ class Comparison extends InfixOperator<bool, BoolType> {
   final Expression left;
   @override
   final Expression right;
+
+  /// The operator to use for this comparison
   final ComparisonOperator op;
 
   @override
   final bool placeBrackets = false;
 
   @override
-  String get operator => operatorNames[op];
+  String get operator => _operatorNames[op];
 
+  /// Constructs a comparison from the [left] and [right] expressions to compare
+  /// and the [ComparisonOperator] [op].
   Comparison(this.left, this.op, this.right);
 
+  /// Like [Comparison(left, op, right)], but uses [ComparisonOperator.equal].
   Comparison.equal(this.left, this.right) : op = ComparisonOperator.equal;
 }

moor/lib/src/runtime/expressions/text.dart

@@ -5,9 +5,13 @@ import 'package:moor/src/types/sql_types.dart';
 /// A `text LIKE pattern` expression that will be true if the first expression
 /// matches the pattern given by the second expression.
 class LikeOperator extends Expression<bool, BoolType> {
+  /// The target expression that will be tested
   final Expression<String, StringType> target;
+
+  /// The regex-like expression to test the [target] against.
   final Expression<String, StringType> regex;
 
+  /// Perform a like operator with the target and the regex.
   LikeOperator(this.target, this.regex);
 
   @override
@@ -41,9 +45,14 @@ enum Collate {
 
 /// A `text COLLATE collate` expression in sqlite.
 class CollateOperator extends Expression<String, StringType> {
+  /// The expression on which the collate function will be run
   final Expression inner;
+
+  /// The [Collate] to use.
   final Collate collate;
 
+  /// Constructs a collate expression on the [inner] expression and the
+  /// [Collate].
   CollateOperator(this.inner, this.collate);
 
   @override

moor/lib/src/runtime/expressions/variables.dart

@@ -7,8 +7,10 @@ import 'package:moor/src/types/sql_types.dart';
 /// An expression that represents the value of a dart object encoded to sql
 /// using prepared statements.
 class Variable<T, S extends SqlType<T>> extends Expression<T, S> {
+  /// The Dart value that will be sent to the database
   final T value;
 
+  /// Constructs a new variable from the [value].
   const Variable(this.value);
 
   /// Creates a variable that holds the specified boolean.
@@ -64,8 +66,10 @@ class Variable<T, S extends SqlType<T>> extends Expression<T, S> {
 /// by writing them into the sql statements. For most cases, consider using
 /// [Variable] instead.
 class Constant<T, S extends SqlType<T>> extends Expression<T, S> {
+  /// Constructs a new constant (sql literal) holding the [value].
   const Constant(this.value);
 
+  /// The value that will be converted to an sql literal.
   final T value;
 
   @override

moor/lib/src/runtime/migration.dart

@@ -5,7 +5,10 @@ import 'package:moor/src/runtime/components/component.dart';
 import 'package:moor/src/runtime/structure/columns.dart';
 import 'package:moor/src/runtime/structure/table_info.dart';
 
+/// Signature of a function that will be invoked when a database is created.
 typedef Future<void> OnCreate(Migrator m);
+
+/// Signature of a function that will be invoked when a database is upgraded.
 typedef Future<void> OnUpgrade(Migrator m, int from, int to);
 
 /// Signature of a function that's called after a migration has finished and the
@@ -24,6 +27,8 @@ Future<void> _defaultOnUpdate(Migrator m, int from, int to) async =>
         "but didn't provide a strategy for schema updates. Please do that by "
         'adapting the migrations getter in your database class.');
 
+/// Handles database migrations by delegating work to [OnCreate] and [OnUpgrade]
+/// methods.
 class MigrationStrategy {
   /// Executes when the database is opened for the first time.
   final OnCreate onCreate;
@@ -38,6 +43,8 @@ class MigrationStrategy {
   /// created or set sqlite `PRAGMAS` that you need.
   final OnBeforeOpen beforeOpen;
 
+  /// Construct a migration strategy from the provided [onCreate] and
+  /// [onUpgrade] methods.
   MigrationStrategy({
     this.onCreate = _defaultOnCreate,
     this.onUpgrade = _defaultOnUpdate,
@@ -48,10 +55,12 @@ class MigrationStrategy {
 /// A function that executes queries and ignores what they return.
 typedef Future<void> SqlExecutor(String sql, [List<dynamic> args]);
 
+/// Runs migrations declared by a [MigrationStrategy].
 class Migrator {
   final GeneratedDatabase _db;
   final SqlExecutor _executor;
 
+  /// Used internally by moor when opening the database.
   Migrator(this._db, this._executor);
 
   /// Creates all tables specified for the database, if they don't exist
@@ -164,6 +173,7 @@ class OpeningDetails {
   /// Whether a schema upgrade was performed while opening the database.
   bool get hadUpgrade => !wasCreated && versionBefore != versionNow;
 
+  /// Used internally by moor when opening a database.
   const OpeningDetails(this.versionBefore, this.versionNow);
 }
 

moor/lib/src/runtime/statements/delete.dart

@@ -5,6 +5,7 @@ import 'package:moor/src/runtime/components/component.dart';
 import 'package:moor/src/runtime/statements/query.dart';
 import 'package:moor/src/runtime/structure/table_info.dart';
 
+/// A `DELETE` statement in sql
 class DeleteStatement<T extends Table, D extends DataClass> extends Query<T, D>
     with SingleTableQueryMixin<T, D> {
   /// This constructor should be called by [GeneratedDatabase.delete] for you.

moor/lib/src/runtime/statements/insert.dart

@@ -4,12 +4,18 @@ import 'package:meta/meta.dart';
 import 'package:moor/moor.dart';
 import 'package:moor/src/runtime/components/component.dart';
 
+/// Represents an insert statements
 class InsertStatement<D extends DataClass> {
+  /// The database to use then executing this statement
   @protected
   final QueryEngine database;
+
+  /// The table we're inserting into
   @protected
   final TableInfo<Table, D> table;
 
+  /// Constructs an insert statement from the database and the table. Used
+  /// internally by moor.
   InsertStatement(this.database, this.table);
 
   /// Inserts a row constructed from the fields in [entity].

moor/lib/src/runtime/statements/query.dart

@@ -11,16 +11,26 @@ import 'package:moor/src/utils/single_transformer.dart';
 /// Statement that operates with data that already exists (select, delete,
 /// update).
 abstract class Query<T extends Table, D extends DataClass> {
+  /// The database this statement should be sent to.
   @protected
   QueryEngine database;
+
+  /// The (main) table this query operates on.
   TableInfo<T, D> table;
 
+  /// Used internally by moor. Users should use the appropriate methods on
+  /// [QueryEngine] instead.
   Query(this.database, this.table);
 
+  /// The `WHERE` clause for this statement
   @protected
   Where whereExpr;
+
+  /// The `ORDER BY` clause for this statement
   @protected
   OrderBy orderByExpr;
+
+  /// The `LIMIT` clause for this statement.
   @protected
   Limit limitExpr;
 

moor/lib/src/runtime/statements/select.dart

@@ -11,17 +11,23 @@ import 'package:moor/src/runtime/expressions/expression.dart';
 import 'package:moor/src/runtime/statements/query.dart';
 import 'package:moor/src/runtime/structure/table_info.dart';
 
+/// Signature of a function that generates an [OrderingTerm] when provided with
+/// a table.
 typedef OrderingTerm OrderClauseGenerator<T>(T tbl);
 
+/// A `SELECT` statement that operates on more than one table.
 class JoinedSelectStatement<FirstT extends Table, FirstD extends DataClass>
     extends Query<FirstT, FirstD>
     with LimitContainerMixin, Selectable<TypedResult> {
+  /// Used internally by moor, users should use [SimpleSelectStatement.join]
+  /// instead.
   JoinedSelectStatement(
       QueryEngine database, TableInfo<FirstT, FirstD> table, this._joins)
       : super(database, table);
 
   final List<Join> _joins;
 
+  /// The tables this select statement reads from
   @visibleForOverriding
   Set<TableInfo> get watchedTables => _tables.toSet();
 
@@ -170,9 +176,12 @@ class JoinedSelectStatement<FirstT extends Table, FirstD extends DataClass>
 class SimpleSelectStatement<T extends Table, D extends DataClass>
     extends Query<T, D>
     with SingleTableQueryMixin<T, D>, LimitContainerMixin<T, D>, Selectable<D> {
+  /// Used internally by moor, users will want to call [QueryEngine.select]
+  /// instead.
   SimpleSelectStatement(QueryEngine database, TableInfo<T, D> table)
       : super(database, table);
 
+  /// The tables this select statement reads from.
   @visibleForOverriding
   Set<TableInfo> get watchedTables => {table};
 

moor/lib/src/runtime/statements/update.dart

@@ -4,8 +4,10 @@ import 'package:moor/moor.dart';
 import 'package:moor/src/runtime/components/component.dart';
 import 'package:moor/src/runtime/expressions/expression.dart';
 
+/// Represents an `UPDATE` statement in sql.
 class UpdateStatement<T extends Table, D extends DataClass> extends Query<T, D>
     with SingleTableQueryMixin<T, D> {
+  /// Used internally by moor, construct an update statement
   UpdateStatement(QueryEngine database, TableInfo<T, D> table)
       : super(database, table);
 

moor/lib/src/runtime/structure/columns.dart

@@ -19,6 +19,8 @@ const VerificationResult _invalidNull = VerificationResult.failure(
 abstract class GeneratedColumn<T, S extends SqlType<T>> extends Column<T, S> {
   /// The sql name of this column.
   final String $name;
+
+  /// [$name], but escaped if it's an sql keyword.
   String get escapedName => escapeIfNeeded($name);
 
   /// The name of the table that contains this column
@@ -36,6 +38,7 @@ abstract class GeneratedColumn<T, S extends SqlType<T>> extends Column<T, S> {
   /// specified. Can be null if no default value is set.
   final Expression<T, S> defaultValue;
 
+  /// Used by generated code.
   GeneratedColumn(this.$name, this.tableName, this.$nullable,
       {this.$customConstraints, this.defaultValue});
 
@@ -67,6 +70,9 @@ abstract class GeneratedColumn<T, S extends SqlType<T>> extends Column<T, S> {
     }
   }
 
+  /// Writes custom constraints that are supported by the Dart api from moor
+  /// (e.g. a `CHECK` for bool columns to ensure that the value is indeed either
+  /// 0 or 1).
   @visibleForOverriding
   void writeCustomConstraints(StringBuffer into) {}
 
@@ -108,11 +114,16 @@ abstract class GeneratedColumn<T, S extends SqlType<T>> extends Column<T, S> {
   }
 }
 
+/// Implementation for [TextColumn].
 class GeneratedTextColumn extends GeneratedColumn<String, StringType>
     implements TextColumn {
+  /// Optional. The minimum text length.
   final int minTextLength;
+
+  /// Optional. The maximum text length.
   final int maxTextLength;
 
+  /// Used by generated code.
   GeneratedTextColumn(
     String name,
     String tableName,
@@ -155,8 +166,10 @@ class GeneratedTextColumn extends GeneratedColumn<String, StringType>
   }
 }
 
+/// Implementation for [BoolColumn].
 class GeneratedBoolColumn extends GeneratedColumn<bool, BoolType>
     implements BoolColumn {
+  /// Used by generated code
   GeneratedBoolColumn(String name, String tableName, bool nullable,
       {String $customConstraints, Expression<bool, BoolType> defaultValue})
       : super(name, tableName, nullable,
@@ -171,6 +184,7 @@ class GeneratedBoolColumn extends GeneratedColumn<bool, BoolType>
   }
 }
 
+/// Implementation for [IntColumn]
 class GeneratedIntColumn extends GeneratedColumn<int, IntType>
     with ComparableExpr
     implements IntColumn {
@@ -190,6 +204,7 @@ class GeneratedIntColumn extends GeneratedColumn<int, IntType>
   @override
   final String typeName = 'INTEGER';
 
+  /// Used by generated code.
   GeneratedIntColumn(
     String name,
     String tableName,
@@ -217,9 +232,11 @@ class GeneratedIntColumn extends GeneratedColumn<int, IntType>
   }
 }
 
+/// Implementation for [DateTimeColumn].
 class GeneratedDateTimeColumn extends GeneratedColumn<DateTime, DateTimeType>
     with ComparableExpr
     implements DateTimeColumn {
+  /// Used by generated code.
   GeneratedDateTimeColumn(
     String $name,
     String tableName,
@@ -233,8 +250,10 @@ class GeneratedDateTimeColumn extends GeneratedColumn<DateTime, DateTimeType>
   String get typeName => 'INTEGER'; // date-times are stored as unix-timestamps
 }
 
+/// Implementation for [BlobColumn]
 class GeneratedBlobColumn extends GeneratedColumn<Uint8List, BlobType>
     implements BlobColumn {
+  /// Used by generated code.
   GeneratedBlobColumn(String $name, String tableName, bool $nullable,
       {String $customConstraints, Expression<Uint8List, BlobType> defaultValue})
       : super($name, tableName, $nullable,
@@ -244,9 +263,11 @@ class GeneratedBlobColumn extends GeneratedColumn<Uint8List, BlobType>
   final String typeName = 'BLOB';
 }
 
+/// Implementation for [RealColumn]
 class GeneratedRealColumn extends GeneratedColumn<double, RealType>
     with ComparableExpr
     implements RealColumn {
+  /// Used by generated code
   GeneratedRealColumn(
     String $name,
     String tableName,

moor/lib/src/runtime/structure/error_handling.dart

@@ -6,38 +6,53 @@ class VerificationMeta {
   /// The dart getter name of the property being validated.
   final String dartGetterName;
 
+  /// Used internally by moor
   const VerificationMeta(this.dartGetterName);
 }
 
 /// Returned by [GeneratedColumn.isAcceptableValue] to provide a description
 /// when a valid is invalid.
 class VerificationResult {
+  /// Whether data for a column passed Dart-side integrity checks
   final bool success;
+
+  /// If not [success]-ful, contains a human readable description of what went
+  /// wrong.
   final String message;
 
+  /// Used internally by moor
   const VerificationResult(this.success, this.message);
+
+  /// Used internally by moor
   const VerificationResult.success()
       : success = true,
         message = null;
+
+  /// Used internally by moor
   const VerificationResult.failure(this.message) : success = false;
 }
 
+/// Used internally by moor for integrity checks.
 class VerificationContext {
   final Map<VerificationMeta, VerificationResult> _errors = {};
 
+  /// Used internally by moor
   bool get dataValid => _errors.isEmpty;
 
+  /// Used internally by moor when inserting
   void handle(VerificationMeta meta, VerificationResult result) {
     if (!result.success) {
       _errors[meta] = result;
     }
   }
 
+  /// Used internally by moor
   void missing(VerificationMeta meta) {
     _errors[meta] = const VerificationResult.failure(
         "This value was required, but isn't present");
   }
 
+  /// Used internally by moor
   void throwIfInvalid(dynamic dataObject) {
     if (dataValid) return;
 

moor/lib/src/types/sql_types.dart

@@ -7,6 +7,7 @@ part 'custom_type.dart';
 /// A type that can be mapped from Dart to sql. The generic type parameter here
 /// denotes the resolved dart type.
 abstract class SqlType<T> {
+  /// Constant constructor so that subclasses can be constant
   const SqlType();
 
   /// Maps the [content] to a value that we can send together with a prepared
@@ -24,6 +25,7 @@ abstract class SqlType<T> {
 /// A mapper for boolean values in sql. Booleans are represented as integers,
 /// where 0 means false and any other value means true.
 class BoolType extends SqlType<bool> {
+  /// Constant constructor used by the type system
   const BoolType();
 
   @override
@@ -50,7 +52,9 @@ class BoolType extends SqlType<bool> {
   }
 }
 
+/// Mapper for string values in sql.
 class StringType extends SqlType<String> {
+  /// Constant constructor used by the type system
   const StringType();
 
   @override
@@ -71,7 +75,9 @@ class StringType extends SqlType<String> {
   mapToSqlVariable(String content) => content;
 }
 
+/// Maps [int] values from and to sql
 class IntType extends SqlType<int> {
+  /// Constant constructor used by the type system
   const IntType();
 
   @override
@@ -86,7 +92,9 @@ class IntType extends SqlType<int> {
   }
 }
 
+/// Maps [DateTime] values from and to sql
 class DateTimeType extends SqlType<DateTime> {
+  /// Constant constructor used by the type system
   const DateTimeType();
 
   @override
@@ -113,7 +121,9 @@ class DateTimeType extends SqlType<DateTime> {
   }
 }
 
+/// Maps [Uint8List] values from and to sql
 class BlobType extends SqlType<Uint8List> {
+  /// Constant constructor used by the type system
   const BlobType();
 
   @override
@@ -130,7 +140,9 @@ class BlobType extends SqlType<Uint8List> {
   mapToSqlVariable(Uint8List content) => content;
 }
 
+/// Maps [double] values from and to sql
 class RealType extends SqlType<double> {
+  /// Constant constructor used by the type system
   const RealType();
 
   @override

moor/lib/src/types/type_system.dart

@@ -3,10 +3,13 @@ import 'package:moor/src/types/sql_types.dart';
 /// Manages the set of [SqlType] known to a database. It's also responsible for
 /// returning the appropriate sql type for a given dart type.
 class SqlTypeSystem {
+  /// The mapping types maintained by this type system.
   final List<SqlType> types;
 
+  /// Constructs a [SqlTypeSystem] from the [types].
   const SqlTypeSystem(this.types);
 
+  /// Constructs a [SqlTypeSystem] from the default types.
   const SqlTypeSystem.withDefaults()
       : this(const [
           BoolType(),

moor/lib/src/utils/lazy_database.dart

@@ -16,6 +16,8 @@ class LazyDatabase extends QueryExecutor {
   /// opened for the first time.
   final DatabaseOpener opener;
 
+  /// Declares a [LazyDatabase] that will run [opener] when the database is
+  /// first requested to be opened.
   LazyDatabase(this.opener);
 
   @override

moor/lib/src/utils/start_with_value_transformer.dart

@@ -9,6 +9,8 @@ typedef LatestValue<T> = T Function();
 class StartWithValueTransformer<T> extends StreamTransformerBase<T, T> {
   final LatestValue<T> _value;
 
+  /// Constructs a stream transformer that will emit what's returned by [_value]
+  /// to new listeners.
   StartWithValueTransformer(this._value);
 
   @override

moor/lib/src/web/sql_js.dart

@@ -9,6 +9,7 @@ import 'dart:typed_data';
 
 Completer<SqlJsModule> _moduleCompleter;
 
+/// Calls the `initSqlJs` function from the native sql.js library.
 Future<SqlJsModule> initSqlJs() {
   if (_moduleCompleter != null) {
     return _moduleCompleter.future;
@@ -36,10 +37,12 @@ void _handleModuleResolved(dynamic module) {
   _moduleCompleter.complete(SqlJsModule._(module as JsObject));
 }
 
+/// `sql.js` module from the underlying library
 class SqlJsModule {
   final JsObject _obj;
   SqlJsModule._(this._obj);
 
+  /// Constructs a new [SqlJsDatabase], optionally from the [data] blob.
   SqlJsDatabase createDatabase([Uint8List data]) {
     final dbObj = _createInternally(data);
     assert(() {
@@ -62,19 +65,23 @@ class SqlJsModule {
   }
 }
 
+/// Dart wrapper around a sql database provided by the sql.js library.
 class SqlJsDatabase {
   final JsObject _obj;
   SqlJsDatabase._(this._obj);
 
+  /// Calls `prepare` on the underlying js api
   PreparedStatement prepare(String sql) {
     final obj = _obj.callMethod('prepare', [sql]) as JsObject;
     return PreparedStatement._(obj);
   }
 
+  /// Calls `run(sql)` on the underlying js api
   void run(String sql) {
     _obj.callMethod('run', [sql]);
   }
 
+  /// Calls `run(sql, args)` on the underlying js api
   void runWithArgs(String sql, List<dynamic> args) {
     final ar = JsArray.from(args);
     _obj.callMethod('run', [sql, ar]);
@@ -98,15 +105,19 @@ class SqlJsDatabase {
     return data.first as int;
   }
 
+  /// Runs `export` on the underlying js api
   Uint8List export() {
     return _obj.callMethod('export') as Uint8List;
   }
 
+  /// Runs `close` on the underlying js api
   void close() {
     _obj.callMethod('close');
   }
 }
 
+/// Dart api wrapping an underlying prepared statement object from the sql.js
+/// library.
 class PreparedStatement {
   final JsObject _obj;
   PreparedStatement._(this._obj);
@@ -116,10 +127,12 @@ class PreparedStatement {
     _obj.callMethod('bind', [JsArray.from(args)]);
   }
 
+  /// Performs `step` on the underlying js api
   bool step() {
     return _obj.callMethod('step') as bool;
   }
 
+  /// Reads the current from the underlying js api
   List<dynamic> currentRow() {
     return _obj.callMethod('get') as JsArray;
   }
@@ -130,6 +143,7 @@ class PreparedStatement {
     return (_obj.callMethod('getColumnNames') as JsArray).cast<String>();
   }
 
+  /// Calls `free` on the underlying js api
   void free() {
     _obj.callMethod('free');
   }

moor/lib/src/web/web_db.dart

@@ -3,6 +3,7 @@ part of 'package:moor/moor_web.dart';
 /// Experimental moor backend for the web. To use this platform, you need to
 /// include the latest version of `sql.js` in your html.
 class WebDatabase extends DelegatedDatabase {
+  /// A database executor that works on the web.
   WebDatabase(String name, {bool logStatements = false})
       : super(_WebDelegate(name),
             logStatements: logStatements, isSequential: true);