branch: elpa/emacsql
commit f31120edb6fe347ab9c81cf29df94a1709e42ed2
Author: Christopher Wellons <well...@nullprogram.com>
Commit: Christopher Wellons <well...@nullprogram.com>
Fix up documentation headers.
---
README.md | 2 +-
emacsql.el | 31 +++++++++++--------------------
2 files changed, 12 insertions(+), 21 deletions(-)
diff --git a/README.md b/README.md
index bd92bb97f1..12a8faa210 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,7 @@ shouldn't impact normal use of the database.
```el
(defvar db (emacsql-connect "/var/lib/company.db"))
-;; Create a table. A table identifier can be any kind of lisp value.
+;; Create a table. Table and column identifiers are symbols.
(emacsql db [:create-table people [name id salary]])
;; Or optionally provide column constraints.
diff --git a/emacsql.el b/emacsql.el
index 79ff8a8d10..64993134b7 100644
--- a/emacsql.el
+++ b/emacsql.el
@@ -10,9 +10,9 @@
;;; Commentary:
;; The purpose of this package is to provide a high-level Elisp
-;; interface to a high-performance database backend. Not every last
-;; feature of SQLite will be exposed at the high-level, but most of it
-;; should be.
+;; interface to a high-performance database backend. Not every feature
+;; of SQLite will be exposed at the high-level, but most of it should
+;; be.
;; Every emacsql function operates on a database connection
;; established with `emacsql-connect', connecting to a SQLite database
@@ -21,20 +21,17 @@
;; (defvar db (emacsql-connect "company.db"))
-;; Database connections are automatically closed when the connection
-;; object is garbage collected. Though this doesn't excuse poor coding
-;; habits! :-)
-
-;; Table identifiers can be any lisp object: string, symbol, etc. I
-;; suggest using a symbol. Use `emacsql-create' to create a table.
+;; Identifiers for tables and columns are symbols. SQL keywords are
+;; lisp keywords. Use `emacsql' for sending structured statements to
+;; the database.
;; (emacsql db [:create-table people [name id salary]])
-;; Column constraints can optionally be provided.
+;; Column constraints can optionally be provided in the schema.
;; (emacsql db [:create-table people [name (id integer :unique) salary]])
-;; Insert values into a table with `emacsql-insert'.
+;; Insert some values.
;; (emacsql db [:insert :into people
;; :values (["Jeff" 1000 60000.0] ["Susan" 1001 64000.0])])
@@ -47,21 +44,15 @@
;; (emacsql db [:select [name id] :from employees :where (> salary 60000)])
;; ;; => (("Susan" 1001))
-;; Queries can be templates using $1, $2, etc.:
+;; Queries can be templates -- $1, $2, etc. -- so they don't need to
+;; be built up dynamically:
;; (emacsql db
;; [:select [name id] :from employees :where (> salary $1)]
;; 50000)
;; ;; => (("Jeff" 1000) ("Susan" 1001))
-;; Limitations:
-
-;; Due to limitations of the SQLite command line program, emacsql is
-;; *not* intended to play well with other programs accessing the
-;; SQLite database. Text values and blobs are stored encoded as
-;; s-expressions in order to avoid ambiguities in parsing output from
-;; the command line. This is a high-performance database specifically
-;; for Emacs.
+;; See README.md for much more complete documentation.
;;; Code:
