From ed6341fff0000568000f728b21d25038fca33d9d Mon Sep 17 00:00:00 2001
From: Tom Willemse <tom@ryuslash.org>
Date: Sun, 29 Dec 2013 01:15:25 +0100
Subject: [PATCH] Update docstrings

---
 edocs.el | 54 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 49 insertions(+), 5 deletions(-)

diff --git a/edocs.el b/edocs.el
index 9fb6f19..e13fbe2 100644
--- a/edocs.el
+++ b/edocs.el
@@ -27,6 +27,15 @@
 
 ;; : emacs -batch -l edocs.el -f edocs-generate-batch file.el
 
+;; Each paragraph of text is exported using `org-mode', currently
+;; requiring at least org version 8.
+
+;; There is `edocs-generate' which can be used to generate a buffer of
+;; the HTML output of the module it's run in interactively, but it is
+;; not meant as the main entry-point for edocs.  The function
+;; `edocs-generate-batch' is the main entry-point of edocs, it is
+;; supposed to be run as a batch procedure as shown above.
+
 ;;; Code:
 
 (require 'help-fns)
@@ -38,13 +47,29 @@
   (require 'cl-macs))
 
 (defvar edocs-stylesheet-location "style.css"
-  "Where to find the Cascading Style Sheet for the exported docs.")
+  "The location of the CSS used by the exported HTML.
+
+By default it uses `style.css'.  This can be changed to any value
+which can be used as the `href' attribute of a `style' tag as it
+is placed verbatim in one.")
 
 (defvar edocs-generate-only-body nil
-  "Whether to genereate only the body and no header/footer info.")
+  "Whether to generate only the body and no header/footer info.
+
+In case the output of edocs is to be embedded into some other
+HTML or similar file this option can be changed so that no HTML
+header of footer tags are output.  Any non-nil value will
+suppress these tags.  The default is nil.")
 
 (defvar edocs-private-regexp "--"
-  "Regular expression to identify private parts of a module's API.")
+  "Regular expression to identify private parts of a module's API.
+
+Some modules (such as this one) differentiate between public and
+private parts of the API.  This regular expression is used to
+identify symbols that are supposed to be private to the module,
+and are not meant to be used outside the module.  The default is
+`--', which matches any symbol with two hyphens such as
+`edocs--symbol-type-map'.")
 
 (defconst edocs--symbol-type-map
   #s(hash-table size 8 test equal
@@ -232,7 +257,13 @@ parts of the module."
           (edocs--normalize docs))))
 
 (defun edocs-generate ()
-  "Generate nice-looking documentation for a module or file."
+  "Generate nice-looking documentation for a module or file.
+
+Markup is handled by `org-mode' exporting functions.  This
+command is used both as an interactive command to test the output
+of this module and called by the `edocs-generate-batch' function
+to generate the actual output.  This command outputs its result
+into a buffer called `*edocs*' and switches to that buffer."
   (interactive)
   (let* ((buffer (get-buffer-create "*edocs*"))
          (binfo (package-buffer-info))
@@ -261,7 +292,20 @@ parts of the module."
     (write-file (concat (file-name-sans-extension file) ".html"))))
 
 (defun edocs-generate-batch ()
-  "Generate module docs using batch operations."
+  "Generate module docs as a batch operation.
+
+This function maps over `command-line-args-left' and tries to
+export the documentation for each file to a file with the same
+name, except for the extension replaced with `.html'.  This
+function uses the `edocs-generate' command to actually generate
+the HTML.
+
+Options which affect the export of module documentation (such as
+`edocs-stylesheet-location') can be changed using the `-eval'
+command line argument to Emacs.  For example:
+
+: emacs -batch -l edocs.el -eval \"(setq edocs-generate-only-body t)\" \\
+:     -f edocs-generate-batch file.el"
   (mapc #'edocs--generate-batch-1 command-line-args-left))
 
 (provide 'edocs)