[nongnu] elpa/emacsql ef4bcec524 321/427: Conform to elisp header conventions

[ELPA Syncer]

branch: elpa/emacsql
commit ef4bcec524d1456cd9aec9d863b2039f44b503d9
Author: Jonas Bernoulli <jonas@bernoul.li>
Commit: Jonas Bernoulli <jonas@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."