docs: more docstrings

Author: johnstonskj

README.md

@@ -126,7 +126,7 @@ display in a read-only window.
 ### Full Validation
 
 * Command `sdml-mode-validate-current-buffer` has the default binding `C-c C-s v`.
-* Command `sdml-mode-validate` has the default binding `C-c C-s M-v`.
+* Command `sdml-mode-validate-file` has the default binding `C-c C-s M-v`.
 * The variable `sdml-mode-validation-level` denotes the level of messages produced
   by the validator, with a default of `warnings`.
 * The output uses the standard `compilation-mode` with all the common bindings are
@@ -169,11 +169,12 @@ or the keyword `"forall"` replaced with the Unicode `∀`.
 * `C-c C-s d` -- open the tree-sitter debug view
 * `C-c C-s q` -- open the tree-sitter query builder
 * `C-c C-s t` -- open a dependency tree view for the current buffer
+* `C-c C-s M-t` -- open a dependency graph image for the current buffer
 * `C-c C-s v` -- run the validator, on the current buffer, and show the results in
   a compilation window
 * `C-c C-s M-v` -- run the validator, on a specified file, and show the results in
   a compilation window
-* `C-c C-s T` -- run u-ctags for the current project
+* `C-c C-s g` -- run u-ctags for the current project
 
 ## Add-Ons
 

sdml-mode-ctags.el

@@ -63,8 +63,20 @@
 
 (defun sdml-mode-ctags-tag-file-path (&optional file-path)
   "Return a path to a tag file for the current buffer.
-If FILE-PATH is provided the tag file is found relative to that
-path instead."
+
+If FILE-PATH is not provided the file name of the current buffer is used
+instead.
+
+If the `company-ctags' package is loaded, use the function
+`company-ctags-find-table' to find a tag file location.
+
+If the `projectile' package is loaded, use the variable
+`projectile-project-root' to determine the directory in which to
+put the tag file named `sdml-mode-ctags-output-file-name'.
+
+If neither of these are present the directory containing FILE-NAME
+will be used as the location for the tag file named
+ `sdml-mode-ctags-output-file-name'."
   (let* ((current-buffer-dir (file-name-directory
                               (or file-path (buffer-file-name))))
          (fallback (concat current-buffer-dir
@@ -78,29 +90,47 @@ path instead."
         (t fallback))))
 
 (defun sdml-mode-ctags-generate ()
-  "Generate a TAGS file for the current SDML project."
+  "Generate a TAGS file for the current SDML project.
+
+This command executes the Universal Ctags executable specified in
+`sdml-mode-ctags-command' to create a tag file determined by the
+function `sdml-mode-ctags-tag-file-path'."
   (interactive)
   (let ((tag-file-path (sdml-mode-ctags-tag-file-path)))
     (shell-command (format "%s -R -e -o %s" sdml-mode-ctags-command tag-file-path))))
 
+
+;; --------------------------------------------------------------------------
+;; Key Bindings
+;; --------------------------------------------------------------------------
+
+(defvar sdml-mode-ctags-mode-map
+  (let ((map (make-sparse-keymap)))
+    (define-key map (kbd "C-c C-s g") 'sdml-mode-ctags-generate))
+  "Key map for SDML ctags minor mode.")
+
+
 ;; --------------------------------------------------------------------------
 ;; Ctags Minor Mode
 ;; --------------------------------------------------------------------------
 
 ;;;###autoload
 (define-minor-mode
   sdml-mode-ctags-mode
-  "Minor mode to provide tagging of SDML source."
+  "Minor mode to provide tagging of SDML source.
+
+Key bindings:
+  \\{sdml-mode-ctags-mode-map}"
 
   :group 'sdml
 
   :tag "Enable SDML tagging minor mode"
 
   :lighter nil
 
-  (let ((map (make-sparse-keymap)))
-    (define-key map (kbd "C-c C-s T") 'sdml-mode-ctags-generate)
-    (add-to-list 'minor-mode-map-alist (cons 'sdml-mode-ctags-mode map)))
+  (add-to-list 'minor-mode-map-alist
+               (cons 'sdml-mode-ctags-mode
+                     sdml-mode-ctags-mode-map))
 
   (when (featurep 'company-ctags)
     (add-to-list 'company-ctags-modes 'sdml-mode)))

sdml-mode.el

@@ -86,14 +86,20 @@
 ;;
 
 ;; `sdml-mode-validate-current-buffer' (\\[sdml-mode-validate-current-buffer]) to
-;; validate and show errors for the buffer's current module.
+;; validate and show errors for the current buffer's module.
 ;;
-;; Adding this as a save-hook allows  validation on every save of a buffer.
+;; Adding this as a save-hook allows validation on every save of a buffer.
 ;;
 ;; `(add-hook 'after-save-hook 'sdml-validate-current-buffer)'
 ;;
+;; `sdml-mode-validate-file' (\\[sdml-mode-validate-file]) to
+;; validate and show errors for a specified file name.
+;;
 ;; `sdml-mode-current-buffer-dependency-tree' (\\[sdml-mode-current-buffer-dependency-tree])
-;; to display the dependencies of the curtent buffer's module.
+;; to display the dependencies of the current buffer's module as a textual tree.
+;;
+;; `sdml-mode-current-buffer-dependency-graph' (\\[sdml-mode-current-buffer-dependency-graph])
+;; to display the dependencies of the current buffer's module as an SVG directed graph.
 ;;
 
 ;; Extensions