[nongnu] elpa/auto-dim-other-buffers d4f5508b4e 30/82: Bumped version to 1.5 and updated docstrings and comments.

[ELPA Syncer]

branch: elpa/auto-dim-other-buffers
commit d4f5508b4e36aeb3ec0b2604697ee64b4e5bb64f
Author: Michal Nazarewicz <mina86@mina86.com>
Commit: Michal Nazarewicz <mina86@mina86.com>

    Bumped version to 1.5 and updated docstrings and comments.
---
 README.md                 | 29 ++++++++++++++++++------
 auto-dim-other-buffers.el | 57 ++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 74 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index fd019d4069..0b19aa2ebd 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,32 @@
 # auto-dim-other-buffers.el
 
-Visually makes non-current buffers less prominent.
+The `auto-dim-other-buffers-mode' is a global minor mode which
+makes non-current buffer less prominent making it more apparent
+which window has a focus.
 
 ![screenshot](screenshot.png)
 
-## Install via [MELPA](http://melpa.milkbox.net/)
+The preferred way to install the mode is by installing a package
+form MELPA:
 
-`M-x` `package-install` `auto-dim-other-buffers`
+    M-x package-install RET auto-dim-other-buffers RET
 
-## Turn it on
+Once installed, the mode can be turned on (globally) with:
 
-`M-x` `auto-dim-other-buffers-mode` (it's a global mode)
+    M-x auto-dim-other-buffers-mode RET
 
-## Customize "dimmed" buffers face
+To make the mode enabled every time Emacs starts, add the following
+to Emacs initialisation file (~/.emacs or ~/.emacs.d/init.el):
 
-By default, "less prominent" means "has a black background". But you might 
want to change that by customizing `auto-dim-other-buffers-face`.
+    (add-hook 'after-init-hook (lambda ()
+      (when (fboundp 'auto-dim-other-buffers-mode)
+        (auto-dim-other-buffers-mode t))))
+
+To configure how dimmed buffers look like, customise
+`auto-dim-other-buffers-face`.  This can be accomplished by:
+
+    M-x customize-face RET auto-dim-other-buffers-face RET
+
+The `auto-dim-other-buffers-mode` is a global minor mode which
+makes non-current buffer less prominent making it more apparent
+which window has a focus.
diff --git a/auto-dim-other-buffers.el b/auto-dim-other-buffers.el
index 3753e909b6..3e2f3d65f5 100644
--- a/auto-dim-other-buffers.el
+++ b/auto-dim-other-buffers.el
@@ -1,8 +1,45 @@
-;;; auto-dim-other-buffers.el --- Visually makes non-current buffers less 
prominent
+;;; auto-dim-other-buffers.el --- Makes non-current buffers less prominent
+
+;; Copyright 2013 Steven Degutis
+;; Copyright 2013,2014 Google Inc.
+;; Copyright 2014 Justin Talbott
 
 ;; Author: Steven Degutis
-;; URL: https://github.com/sdegutis/auto-dim-other-buffers.el
-;; Version: 1.4
+;;         Michal Nazarewicz <mina86@mina86.com>
+;; Maintainer: Michal Nazarewicz <mina86@mina86.com>
+;; URL: https://github.com/mina86/auto-dim-other-buffers.el
+;; Version: 1.5
+
+;; This file is not part of GNU Emacs.
+
+;;; Commentary:
+
+;; The `auto-dim-other-buffers-mode' is a global minor mode which
+;; makes non-current buffer less prominent making it more apparent
+;; which window has a focus.
+
+;; The preferred way to install the mode is by installing a package
+;; form MELPA:
+;;
+;;     M-x package-install RET auto-dim-other-buffers RET
+
+;; Once installed, the mode can be turned on (globally) with:
+;;
+;;     M-x auto-dim-other-buffers-mode RET
+
+;; To make the mode enabled every time Emacs starts, add the following
+;; to Emacs initialisation file (~/.emacs or ~/.emacs.d/init.el):
+;;
+;;     (add-hook 'after-init-hook (lambda ()
+;;       (when (fboundp 'auto-dim-other-buffers-mode)
+;;         (auto-dim-other-buffers-mode t))))
+
+;; To configure how dimmed buffers look like, customise
+;; `auto-dim-other-buffers-face'.  This can be accomplished by:
+;;
+;;     M-x customize-face RET auto-dim-other-buffers-face RET
+
+;;; Code:
 
 (defface auto-dim-other-buffers-face '((t :background "black"))
   "Face (presumably dimmed somehow) for non-current buffers."
@@ -12,14 +49,18 @@
   "Buffer we were before command finished.")
 
 (defun adob--ignore-buffer (buffer)
+  "Return whether to ignore BUFFER and do not affect it's state.
+Currently only mini buffer and echo areas are ignored."
   (or (null buffer)
       (minibufferp buffer)
       (string-match "^ \\*Echo Area" (buffer-name buffer))))
 
 (defun adob--pre-command-hook ()
+  "Record current buffer before the command is run."
   (setq adob--last-buffer (current-buffer)))
 
 (defun adob--post-command-hook ()
+  "If buffer has changed, dim the last one and undim the new one."
   ;; if we haven't switched buffers, do nothing
   (unless (eq (current-buffer) adob--last-buffer)
 
@@ -34,13 +75,15 @@
     ;; now, restore the current buffer, and undim it.
     (buffer-face-set nil)))
 
-;; if a new window pops up, like a help window or something, we
-;; should dim or undim it, depending on if its selected.
 (defun adob--after-change-major-mode-hook ()
+  "Dim or undim a new buffer if a new window, like help window, has popped up."
   (buffer-face-set (unless (eq (current-buffer) (window-buffer))
                      'auto-dim-other-buffers-face)))
 
 (defun adob--set-face-on-all-buffers (face)
+  "Set FACE on all buffers which are not to be ignored.
+Whether buffer should be ignored is determined by `adob--ignore-buffer'
+function."
   (save-current-buffer
     (dolist (buffer (buffer-list))
       (unless (adob--ignore-buffer buffer)
@@ -48,12 +91,15 @@
         (buffer-face-set face)))))
 
 (defun adob--undim-all-buffers ()
+  "Undim all buffers."
   (adob--set-face-on-all-buffers nil))
 
 (defun adob--dim-all-buffers ()
+  "Dim all buffers."
   (adob--set-face-on-all-buffers 'auto-dim-other-buffers-face))
 
 (defun turn-off-auto-dim-other-buffers ()
+  "Turn `auto-dim-other-buffers-mode' off."
   (remove-hook 'pre-command-hook 'adob--pre-command-hook)
   (remove-hook 'post-command-hook 'adob--post-command-hook)
   (remove-hook 'focus-out-hook 'adob--dim-all-buffers)
@@ -64,6 +110,7 @@
   (adob--undim-all-buffers))
 
 (defun turn-on-auto-dim-other-buffers ()
+  "Turn `auto-dim-other-buffers-mode' on."
   (setq adob--last-buffer nil)
   (adob--dim-all-buffers)
   (add-hook 'pre-command-hook 'adob--pre-command-hook)