From 6e0954389363ca0d370f418a289ad2b3b12f8642 Mon Sep 17 00:00:00 2001
From: vindarel <vindarel@mailz.org>
Date: Wed, 23 Sep 2020 12:45:26 +0200
Subject: [PATCH 1/2] doc: add documentation string for user-facing methods

---
 src/core/dao.lisp | 48 +++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 42 insertions(+), 6 deletions(-)

diff --git a/src/core/dao.lisp b/src/core/dao.lisp
index 4c66cdb..c35ac63 100644
--- a/src/core/dao.lisp
+++ b/src/core/dao.lisp
@@ -139,7 +139,8 @@
   (:method :before ((obj record-timestamps-mixin))
     (let ((now (local-time:now)))
       (setf (object-created-at obj) now)
-      (setf (object-updated-at obj) now))))
+      (setf (object-updated-at obj) now)))
+  (:documentation "Insert the object OBJ into the DB."))
 
 (defgeneric create-dao (class &rest initargs)
   (:method ((class-name symbol) &rest initargs)
@@ -147,7 +148,20 @@
   (:method ((class dao-table-class) &rest initargs)
     (let ((obj (apply #'make-instance class initargs)))
       (setf (dao-synced obj) nil)
-      (save-dao obj))))
+      (save-dao obj)))
+  (:documentation "Create an object of class CLASS with INITARGS and save it into the DB.
+
+Example:
+
+(mito:create-dao 'user :name \"Eitaro Fukamachi\" :email \"e.arrows@gmail.com\")
+
+same as:
+
+(defvar me
+  (make-instance 'user :name \"Eitaro Fukamachi\" :email \"e.arrows@gmail.com\"))
+;=> USER
+
+(mito:insert-dao me)"))
 
 (defgeneric update-dao (obj &key columns)
   (:method ((obj dao-class) &key columns)
@@ -167,7 +181,8 @@
   (:method :before ((obj record-timestamps-mixin) &key columns)
     (declare (ignore columns))
     (let ((now (local-time:now)))
-      (setf (object-updated-at obj) now))))
+      (setf (object-updated-at obj) now)))
+  (:documentation "Update the object OBJ into the DB."))
 
 (defgeneric delete-dao (obj)
   (:method ((obj dao-class))
@@ -184,7 +199,8 @@
                                  `(:= ,(unlispify key) ,(slot-value obj key)))
                                primary-key)))))
         (setf (dao-synced obj) nil)))
-    (values)))
+    (values))
+  (:documentation "Delete the object OBJ from the DB."))
 
 (defgeneric delete-by-values (class &rest fields-and-values)
   (:method ((class symbol) &rest fields-and-values)
@@ -194,13 +210,16 @@
       (execute-sql
        (sxql:delete-from (sxql:make-sql-symbol (table-name class))
          (where-and fields-and-values class))))
-    (values)))
+    (values))
+  (:documentation "Delete the records of class CLASS matching FIELDS-AND-VALUES from the DB.
+For example: (mito:delete-by-values 'user :id 1)"))
 
 (defgeneric save-dao (obj)
   (:method ((obj dao-class))
     (if (dao-synced obj)
         (update-dao obj)
-        (insert-dao obj))))
+        (insert-dao obj)))
+  (:documentation "Save the object OBJ into the DB."))
 
 (defstruct mito-cursor
   cursor
@@ -342,6 +361,23 @@
 (defparameter *want-cursor* nil)
 
 (defmacro select-dao (class &body clauses)
+  "Build custom queries with SxQL.
+
+Example:
+
+  (select-dao 'tweet
+    (where (:like :status \"%Japan%\")))
+
+You can use \"includes\" to eagerly load another table and prevent the \"N+1 query\" performance problem.
+
+Example:
+
+  (defvar *tweets-contain-japan*
+    (select-dao 'tweet
+      (includes 'user)
+      (where (:like :status \"%Japan%\"))))
+
+See the SxQL documentation for the available clauses and operators."
   (with-gensyms (sql clause results include-classes foreign-class)
     (once-only (class)
       `(#+sb-package-locks locally #+sb-package-locks (declare (sb-ext:disable-package-locks sxql:where))

From 68444c4a9ed50edacd3ef7725a143f688c9841b0 Mon Sep 17 00:00:00 2001
From: vindarel <vindarel@mailz.org>
Date: Thu, 29 Aug 2024 20:29:22 +0200
Subject: [PATCH 2/2] README: mention that DB drivers are required for a
 binary.

[ci skip]
---
 README.markdown | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/README.markdown b/README.markdown
index 77aeff9..a077aa2 100644
--- a/README.markdown
+++ b/README.markdown
@@ -640,6 +640,11 @@ Or, with Roswell:
 ros install mito
 ```
 
+If you build a binary, reference a DB driver in your dependencies:
+
+    :dbd-sqlite3 :dbd-mysql :dbd-postgres
+
+
 ## See Also
 
 * [CL-DBI](https://github.com/fukamachi/cl-dbi)