branch: elpa/emacsql
commit ef4bcec524d1456cd9aec9d863b2039f44b503d9
Author: Jonas Bernoulli <jo...@bernoul.li>
Commit: Jonas Bernoulli <jo...@bernoul.li>
Conform to elisp header conventions
Headings should begin with at least three semicolons. Top-level
sections are prefixed with three, subsections with four and so on.
From `(elisp)Comment Tips':
`;;;'
Comments that start with three semicolons, `;;;', should start at
the left margin. We use them for comments which should be
considered a "heading" by Outline minor mode. By default,
comments starting with at least three semicolons (followed by a
single space and a non-whitespace character) are considered
headings, comments starting with two or fewer are not.
Historically, triple-semicolon comments have also been used for
commenting out lines within a function, but this use is
discouraged.
When commenting out entire functions, use two semicolons.
`;;;;'
Comments that start with four semicolons, `;;;;', should be aligned
to the left margin and are used for headings of major sections of a
program. For example:
The trailing colons are redundant, except after "Commentary" and "Code",
where `lisp-mnt.el' unfortunately expects them. "Code:" is necessary
because, in some contexts, it also serves as the terminator for
"Commentary:".
Do not nest other code sections inside "Code:", departing a bit from
what is said about ";;;;" above. Instead define other code sections as
top sections too, and treat "Code:" only as the first code section and
use it for "dependencies and other setup". Add a few additional
sections to avoid putting to much non-setup code inside "Code:".
---
emacsql-compiler.el | 8 +++++---
emacsql-sqlite.el | 10 +++++++---
emacsql-system.el | 2 --
emacsql.el | 14 ++++++++------
4 files changed, 20 insertions(+), 14 deletions(-)
diff --git a/emacsql-compiler.el b/emacsql-compiler.el
index 8879c97748..2b66d1f389 100644
--- a/emacsql-compiler.el
+++ b/emacsql-compiler.el
@@ -4,6 +4,8 @@
(require 'cl-lib)
+;;; Error symbols
+
(defmacro emacsql-deferror (symbol parents message)
"Defines a new error symbol for EmacSQL."
(declare (indent 2))
@@ -30,7 +32,7 @@
"Like `error', but signal an emacsql-syntax condition."
(signal 'emacsql-syntax (list (apply #'format format args))))
-;; Escaping functions:
+;;; Escaping functions
(defvar emacsql-reserved (make-hash-table :test 'equal)
"Collection of all known reserved words, used for escaping.")
@@ -96,7 +98,7 @@ KIND should be :scalar or :identifier."
(:vector (emacsql-escape-vector thing))
(otherwise thing))))
-;; Schema compiler:
+;;; Schema compiler
(defvar emacsql-type-map
'((integer "&INTEGER")
@@ -159,7 +161,7 @@ KIND should be :scalar or :identifier."
(mapcar #'emacsql--prepare-constraints constraints))
", "))))
-;; Statement compilation:
+;;; Statement compilation
(defvar emacsql-prepare-cache (make-hash-table :test 'equal :weakness 'key)
"Cache used to memoize `emacsql-prepare'.")
diff --git a/emacsql-sqlite.el b/emacsql-sqlite.el
index b9fd801060..ab81150ff9 100644
--- a/emacsql-sqlite.el
+++ b/emacsql-sqlite.el
@@ -9,6 +9,8 @@
(require 'emacsql)
(require 'emacsql-system)
+;;; Options
+
(defcustom emacsql-sqlite-automatic-fetch nil
"If non-nil, the user will not be prompted to download the
pre-built SQLite binary. A value of `yes' will always approve the
@@ -26,6 +28,8 @@ version."
:group 'emacsql
:type 'boolean)
+;;; SQLite connection
+
(defvar emacsql-sqlite-executable
(expand-file-name (format "bin/emacsql-sqlite-%s%s" (emacsql-system-tuple)
(if (memq system-type '(windows-nt cygwin ms-dos))
@@ -120,7 +124,7 @@ buffer. This is for debugging purposes."
'emacsql-error)
(list message)))
-;; SQLite compilation
+;;; SQLite compilation
(defun emacsql-sqlite-compile-switches ()
"Return the compilation switches from the Makefile under sqlite/."
@@ -159,7 +163,7 @@ If called with non-nil ASYNC the return value is
meaningless."
(eql 0 (apply #'call-process cc nil (if async 0 t) t
arguments)))))))))
-;; SQLite binary fetching
+;;; SQLite binary fetching
(defvar emacsql-sqlite-user-prompted nil
"To avoid prompting for fetch multiple times.")
@@ -208,7 +212,7 @@ This works like `url-copy-file' but actually checks for
errors."
(emacsql-sqlite-mark-exec emacsql-sqlite-executable)
:success)))))
-;; Ensure the SQLite binary is available
+;;; Ensure the SQLite binary is available
(defun emacsql-sqlite-ensure-binary ()
"Ensure the EmacSQL SQLite binary is available, signaling an error if not."
diff --git a/emacsql-system.el b/emacsql-system.el
index ec05bff153..a19be7ee4a 100644
--- a/emacsql-system.el
+++ b/emacsql-system.el
@@ -1,7 +1,5 @@
;;; emacsql-system.el --- detect OS and machine -*- lexical-binding: t; -*-
-;;; Commentary:
-
;;; Code:
(require 'cl-lib)
diff --git a/emacsql.el b/emacsql.el
index 0bdbece14f..cdcd784b0a 100644
--- a/emacsql.el
+++ b/emacsql.el
@@ -86,6 +86,8 @@ If nil, wait forever.")
(file-name-directory (or load-file-name buffer-file-name))
"Directory where EmacSQL is installed.")
+;;; Database connection
+
(defclass emacsql-connection ()
((process :type process
:initarg :process
@@ -138,7 +140,7 @@ MESSAGE should not have a newline on the end."
(setf (point) (point-max))
(princ (concat message "\n") log)))))
-;; Sending and receiving:
+;;; Sending and receiving
(defgeneric emacsql-send-message ((connection emacsql-connection) message)
"Send MESSAGE to CONNECTION.")
@@ -182,7 +184,7 @@ MESSAGE should not have a newline on the end."
(emacsql-wait connection)
(emacsql-parse connection)))
-;; Helper mixin class:
+;;; Helper mixin class
(defclass emacsql-protocol-mixin ()
()
@@ -220,14 +222,14 @@ specific error conditions."
(provide 'emacsql) ; end of generic function declarations
-;; Automatic connection cleanup:
+;;; Automatic connection cleanup
(defun emacsql-register (connection)
"Register CONNECTION for automatic cleanup and return CONNECTION."
(finalize-register connection #'emacsql-close (copy-sequence connection))
connection)
-;; Useful macros:
+;;; Useful macros
(require 'emacsql-sqlite) ; for `emacsql-connect'
@@ -326,7 +328,7 @@ Each column must be a plain symbol, no expressions allowed
here."
(cl-destructuring-bind ,(cl-coerce vars 'list) emacsql--result
,@body)))))))
-;; User interaction functions:
+;;; User interaction functions
(defvar emacsql-show-buffer-name "*emacsql-show*"
"Name of the buffer for displaying intermediate SQL.")
@@ -383,7 +385,7 @@ A prefix argument causes the SQL to be printed into the
current buffer."
(emacsql-show-sql sql)))
(user-error "Invalid SQL: %S" sexp))))
-;; Fix Emacs' broken vector indentation:
+;;; Fix Emacs' broken vector indentation
(defun emacsql--inside-vector-p ()
"Return non-nil if point is inside a vector expression."
