From 4e97d8621e75a22f5aa1ec40fd9df1495b56dd94 Mon Sep 17 00:00:00 2001
From: Bastien <bzg@gnu.org>
Date: Sat, 28 Apr 2018 00:46:25 +0200
Subject: [PATCH] org-tempo.el: Enhance a few docstrings

* lisp/org-tempo.el (org-tempo, org-tempo-keywords-alist)
(org-tempo-setup, org-tempo-add-templates)
(org-tempo--include-file): Enhance docstrings.
---
 lisp/org-tempo.el | 25 ++++++++++++-------------
 1 file changed, 12 insertions(+), 13 deletions(-)

diff --git a/lisp/org-tempo.el b/lisp/org-tempo.el
index e1268b893..b9a554ff7 100644
--- a/lisp/org-tempo.el
+++ b/lisp/org-tempo.el
@@ -46,12 +46,12 @@
 
 
 (defgroup org-tempo nil
-  "Options for template expansion of Org structures"
+  "Template expansion of Org structures."
   :tag "Org structure"
   :group 'org)
 
 (defvar org-tempo-tags nil
-  "Tempo tags for Org mode")
+  "Tempo tags for Org mode.")
 
 (defcustom org-tempo-keywords-alist
   '(("L" . "latex")
@@ -60,14 +60,13 @@
     ("i" . "index"))
   "Keyword completion elements.
 
-Like `org-structure-template-alist' this alist of KEY characters
-and KEYWORD.  The tempo snippet \"<KEY\" is expand to the KEYWORD
-value.
+This is an alist of KEY characters and corresponding KEYWORDS,
+just like `org-structure-template-alist'.  The tempo snippet
+\"<KEY\" will be expanded using the KEYWORD value.  For example
+\"<l\" at the beginning of a line is expanded to \"#+latex:\".
 
-For example \"<l\" at the beginning of a line is expanded to
-\"#+latex:\".
-
-Note: the tempo function for \"#+include\" is defined elsewhere."
+Do not use \"I\" as a KEY, as it it reserved for expanding
+\"#+include\"."
   :group 'org-tempo
   :type '(repeat (cons (string :tag "Key")
 		       (string :tag "Keyword")))
@@ -78,6 +77,7 @@ Note: the tempo function for \"#+include\" is defined elsewhere."
 ;;; Org Tempo functions and setup.
 
 (defun org-tempo-setup ()
+  "Setup tempo tags and match finder for the current buffer."
   (org-tempo--update-maybe)
   (tempo-use-tag-list 'org-tempo-tags)
   (setq-local tempo-match-finder "^ *\\(<[[:word:]]+\\)\\="))
@@ -100,8 +100,8 @@ Tempo templates will be added."
 (defun org-tempo-add-templates ()
   "Update all Org Tempo templates.
 
-Goes through `org-structure-template-alist' and
-`org-tempo-keywords-alist'."
+Go through `org-structure-template-alist' and
+`org-tempo-keywords-alist' and update tempo templates."
   (let ((keys (org-tempo--keys)))
     ;; Check for duplicated snippet keys and warn if any are found.
     (when (> (length keys) (length (delete-dups keys)))
@@ -151,7 +151,7 @@ didn't succeed."
 ;;; Additional keywords
 
 (defun org-tempo--include-file ()
-  "Ask for file name and take care of quit"
+  "Add #+include: and a file name."
   (let ((inhibit-quit t))
     (unless (with-local-quit
 	      (prog1 t
@@ -168,7 +168,6 @@ didn't succeed."
 		       "<I"
 		       "Include keyword"
 		       'org-tempo-tags)
-
 
 ;;; Setup of Org Tempo
 ;;