Add docstrings

persistent-outline.el

@@ -49,7 +49,31 @@
 (defvar perso-outline)
 
 (defun perso-outline-state ()
-  ""
+  "Determine the state of the headline at point.
+
+The state is determined by looking at the current headline and
+the next.
+
+- If the current heading has been collapsed and the next is
+  completely invisible the current heading is considered to have
+  its complete sub-tree hidden and the symbol `subtree-hidden' is
+  returned.
+
+- If the current heading has been collapsed, the next is visible
+  and its level is lower (higher value, being a child) than the
+  current heading, the current heading is considered to only have
+  its entry text hidden and the symbol `entry-hidden' is
+  returned.
+
+- If the current heading has been collapsed, the next is visible
+  and its level is higher or equal (lower or equal value, being
+  parent or sibling) to the current heading, the current heading
+  is again considered to have its complete sub-tree hidden and
+  the symbol `subtree-hidden' is returned.
+
+In any other case the entry is considered to be fully visible and
+the symbol `entry-visible' is returned.  The entry's leaves may
+still be hidden, but those should be handled separately."
   (when (outline-on-heading-p)
     (let* ((current-level (outline-level))
            (current-invisible (outline-invisible-p (line-end-position)))
@@ -65,7 +89,7 @@
        (t 'entry-visible)))))
 
 (defun perso-record-outline ()
-  ""
+  "Get a list of all the visible outline states in the buffer."
   (save-excursion
     (goto-char (point-min))
     (let ((states (when (outline-on-heading-p)
@@ -79,6 +103,7 @@
       (reverse states))))
 
 (defun perso-apply-outline (outlines)
+  "Apply the outline states in OUTLINES to the current buffer."
   (mapc (lambda (outline)
           (case (cadr outline)
             (entry-visible nil)
@@ -91,23 +116,30 @@
         outlines))
 
 (defun perso--get-filename (file)
+  "Get a filename for FILE to store some information in.
+
+The way the filename is created has been inspired by the
+functions for creating backup and autosave filenames."
   (concat persistent-outline-storage-directory
           (subst-char-in-string
            ?/ ?! (replace-regexp-in-string "!" "!!" buffer-file-name))))
 
 (defun perso--ensure-directory (file)
+  "Make sure that the directory for FILE exists."
   (let ((directory (file-name-directory file)))
     (unless (file-exists-p directory)
       (make-directory directory :parents))))
 
 (defmethod perso-save-to-storage ((storage perso-file-local-storage)
                                   outline)
+  "Save the current states to a file-local variable."
   (let ((modifiedp (buffer-modified-p)))
     (add-file-local-variable 'perso-outline outline)
     (set (make-local-variable 'perso-outline) outline)))
 
 (defmethod perso-save-to-storage ((storage perso-filesystem-storage)
                                   outline)
+  "Save the current state to a dedicated file somewhere."
   (let ((filename (perso--get-filename buffer-file-name)))
     (perso--ensure-directory filename)
     (with-temp-buffer
@@ -115,10 +147,12 @@
       (write-file filename))))
 
 (defmethod perso-load-from-storage ((storage perso-file-local-storage))
+  "Load saved states from a file-local variable."
   (when (boundp (make-local-variable 'perso-outline))
     (symbol-value 'perso-outline)))
 
 (defmethod perso-load-from-storage ((storage perso-filesystem-storage))
+  "Load saved states from a dedicated file somewhere."
   (let ((filename (perso--get-filename buffer-file-name)))
     (when (file-exists-p filename)
       (with-temp-buffer
@@ -129,12 +163,20 @@
 (put 'perso-outline 'safe-local-variable 'listp)
 
 (defun persistent-outline-save ()
+  "Save the current outline state.
+
+The way the outline is saved depends on the value of the
+`persistent-outline-storage' user-option."
   (interactive)
   (save-excursion
     (perso-save-to-storage (make-instance persistent-outline-storage)
                            (perso-record-outline))))
 
 (defun persistent-outline-load ()
+  "Load a saved outline state.
+
+The way the outline is loaded depends on the value of the
+`persistent-outline-storage' user-option."
   (interactive)
   (save-excursion
     (perso-apply-outline
@@ -143,7 +185,14 @@
 
 ;;;###autoload
 (define-minor-mode persistent-outline-mode
-  ""
+  "This minor mode adds a function to the `before-save-hook' hook.
+
+This function saves the current outline state each time the
+buffer is saved. The saved state is also loaded when this minor
+mode is enabled.
+
+Be sure to save the state of the outlines before disabling this
+minor mode as it is not saved automatically in this case."
   nil "P" nil
   :group 'outlines
   (if persistent-outline-mode