Expand docs on how write database / dao classes

.travis.yml

@@ -10,12 +10,6 @@ env:
 script: ./tool/mono_repo_wrapper.sh
 after_success: ./tool/upload_coverage.sh
 
-# Only building master means that we don't run two builds for each pull request.
-branches:
-  only:
-    - master
-    - develop
-
 cache:
   directories:
     - "$HOME/.pub-cache"

moor/lib/src/dsl/database.dart

@@ -3,6 +3,17 @@ import 'package:moor/moor.dart';
 
 /// Use this class as an annotation to inform moor_generator that a database
 /// class should be generated using the specified [UseMoor.tables].
+///
+/// To write a database class, first annotate an empty class with [UseMoor] and
+/// run the build runner using (flutter packages) pub run build_runner build.
+/// Moor will have generated a class that has the same name as your database
+/// class, but with `_$` as a prefix. You can now extend that class and provide
+/// a [QueryEngine] to use moor:
+/// ```dart
+/// class MyDatabase extends _$MyDatabase { // _$MyDatabase was generated
+///   MyDatabase() : super(FlutterQueryExecutor.inDatabaseFolder(path: 'path.db'));
+/// }
+/// ```
 class UseMoor {
   /// The tables to include in the database
   final List<Type> tables;
@@ -10,6 +21,8 @@ class UseMoor {
   /// Optionally, the list of daos to use. A dao can also make queries like a
   /// regular database class, making is suitable to extract parts of your
   /// database logic into smaller components.
+  ///
+  /// For instructions on how to write a dao, see the documentation of [UseDao]
   final List<Type> daos;
 
   /// Use this class as an annotation to inform moor_generator that a database
@@ -17,8 +30,24 @@ class UseMoor {
   const UseMoor({@required this.tables, this.daos = const []});
 }
 
-/// Annotation to use on classes that implement [DatabaseAccessor]. It specified
-/// which tables should be managed in this dao.
+/// Annotation to use on classes that implement [DatabaseAccessor]. It specifies
+/// which tables should be made available in this dao.
+///
+/// To write a dao, you'll first have to write a database class. See [UseMoor]
+/// for instructions on how to do that. Then, create an empty class that is
+/// annotated with [UseDao] and that extends [DatabaseAccessor]. For instance,
+/// if you have a class called `MyDatabase`, this could look like this:
+/// ```dart
+/// class MyDao extends DatabaseAccessor<MyDatabase> {
+///   TodosDao(MyDatabase db) : super(db);
+/// }
+/// ```
+/// After having run the build step once more, moor will have generated a mixin
+/// called `_$MyDaoMixin`. Change your class definition to
+/// `class MyDao extends DatabaseAccessor<MyDatabase> with _$MyDaoMixin` and
+/// you're ready to make queries inside your dao. You can obtain an instance of
+/// that dao by using the getter that will be generated inside your database
+/// class.
 class UseDao {
   /// The tables accessed by this DAO.
   final List<Type> tables;

moor/lib/src/runtime/database.dart

@@ -8,9 +8,11 @@ import 'package:moor/src/runtime/statements/select.dart';
 import 'package:moor/src/runtime/statements/update.dart';
 
 /// Class that runs queries to a subset of all available queries in a database.
+///
 /// This comes in handy to structure large amounts of database code better: The
 /// migration logic can live in the main [GeneratedDatabase] class, but code
 /// can be extracted into [DatabaseAccessor]s outside of that database.
+/// For details on how to write a dao, see [UseDao].
 abstract class DatabaseAccessor<T extends GeneratedDatabase>
     extends DatabaseConnectionUser with QueryEngine {
   @protected

moor_flutter/example/lib/database/todos_dao.dart

@@ -6,7 +6,7 @@ import 'database.dart';
 part 'todos_dao.g.dart';
 
 @UseDao(tables: [Todos])
-class TodosDao extends DatabaseAccessor<Database> with _TodosDaoMixin {
+class TodosDao extends DatabaseAccessor<Database> with _$TodosDaoMixin {
   TodosDao(Database db) : super(db);
 
   Stream<List<TodoEntry>> todosInCategory(Category category) {

moor_flutter/example/lib/database/todos_dao.g.dart

@@ -6,6 +6,6 @@ part of 'todos_dao.dart';
 // DaoGenerator
 // **************************************************************************
 
-mixin _TodosDaoMixin on DatabaseAccessor<Database> {
+mixin _$TodosDaoMixin on DatabaseAccessor<Database> {
   $TodosTable get todos => db.todos;
 }

moor_generator/lib/src/dao_generator.dart

@@ -41,7 +41,7 @@ class DaoGenerator extends GeneratorForAnnotation<UseDao> {
 
     final daoName = enclosingClass.displayName;
 
-    buffer.write('mixin _${daoName}Mixin on '
+    buffer.write('mixin _\$${daoName}Mixin on '
         'DatabaseAccessor<${dbImpl.displayName}> {\n');
 
     for (var table in tableTypes) {