Improve documentation for updated features in 1.3

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

@@ -2,13 +2,20 @@ import 'package:moor/moor.dart';
 import 'package:moor/src/runtime/components/component.dart';
 import 'package:moor/src/runtime/expressions/expression.dart';
 
+/// A custom expression that can appear in a sql statement.
+/// The [CustomExpression.content] will be written into the query without any
+/// modification.
+///
+/// When this statement appears in a query
+///
+/// See also:
+///  - [currentDate] and [currentDateAndTime], which use a [CustomExpression]
+///  internally.
 class CustomExpression<D, S extends SqlType<D>> extends Expression<D, S> {
   final String content;
 
   const CustomExpression(this.content);
 
   @override
-  void writeInto(GenerationContext context) {
+  void writeInto(GenerationContext context) => context.buffer.write(content);
-    context.buffer.write(content);
-  }
 }

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

@@ -69,6 +69,21 @@ class JoinedSelectStatement<FirstT, FirstD> extends Query<FirstT, FirstD>
     }
   }
 
+  /// Applies the [predicate] as the where clause, which will be used to filter
+  /// results.
+  ///
+  /// The clause should only refer to columns defined in one of the tables
+  /// specified during [SimpleSelectStatement.join].
+  ///
+  /// With the example of a todos table which refers to categories, we can write
+  /// something like
+  /// ```dart
+  /// final query = select(todos)
+  /// .join([
+  ///   leftOuterJoin(categories, categories.id.equalsExp(todos.category)),
+  /// ])
+  /// ..where(and(todos.name.like("%Important"), categories.name.equals("Work")));
+  /// ```
   void where(Expression<bool, BoolType> predicate) {
     if (whereExpr == null) {
       whereExpr = Where(predicate);
@@ -77,10 +92,13 @@ class JoinedSelectStatement<FirstT, FirstD> extends Query<FirstT, FirstD>
     }
   }
 
+  /// Orders the results of this staemen
   void orderBy(List<OrderingTerm> terms) {
     orderByExpr = OrderBy(terms);
   }
 
+  /// Creates an auto-updating stream of the result that emits new items
+  /// whenever any table of this statement changes.
   Stream<List<TypedResult>> watch() {
     final ctx = constructQuery();
     final fetcher = QueryStreamFetcher<List<TypedResult>>(
@@ -258,8 +276,8 @@ class CustomSelectStatement {
   }
 }
 
-/// A result row in a [JoinedSelectStatement] that can consist of multiple
+/// A result row in a [JoinedSelectStatement] that can parse the result of
-/// entities.
+/// multiple entities.
 class TypedResult {
   /// Creates the result from the parsed table data.
   TypedResult(this._parsedData, this.rawData);