[elpa] externals/kind-icon 918eb89 06/51: Docs

[ELPA Syncer]

branch: externals/kind-icon
commit 918eb8996c94a3fe0bd442f5edd99c859a8f01fa
Author: JD Smith <93749+jdtsmith@users.noreply.github.com>
Commit: JD Smith <93749+jdtsmith@users.noreply.github.com>

    Docs
---
 README.md      | 29 ++++++++++++++++++++++++++++-
 kind-prefix.el | 18 ++++++++++--------
 2 files changed, 38 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 7f8ae03..9881e24 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,29 @@
 # kind-prefix
-Completion kind text/icon prefix labelling for emacs in-region completion 
+_Kind_ icon or short-text prefix badge labels for emacs in-region completion. 
+
+This emacs package adds icon or text-based completion prefixes based on the 
`:company-kind` property many completion backends (such as lsp-mode) provide.  
It works by creating a custom `affixation-function` for in-buffer completion, 
if the backend does not already provide one.  An affixation function specifies 
a prefix and suffix to go along with completion candidate text.
+
+## Installation 
+
+Get it from melpa (TBD).  Enable in any buffer with completion enabled using 
`kind-prefix-mode`, e.g., to enable for the completion UI 
[corfu](https://github.com/minad/corfu):
+
+```elisp
+(use-package kind-prefix ;package availability TBD
+  :ensure t
+  :hook (corfu-mode . kind-prefix-mode))
+```
+
+## Configuration
+
+Defaults should normally work fine, but some of the important configuration 
variables include:
+
+`kind-prefix-use-icons`: If non-nil (the default), prefer icons for prefix 
badges.
+
+`kind-prefix-mapping`: This is the top level configuration mapping 
`:company-kind` "types" like `'variable` and `'function`.  Each item in this 
list has the format `sym short-text plist` where `sym` is the kind (a symbol), 
short-text is the abbreviated text to display (if icons are not used).  The 
`plist` is a property list with optional keys `:icon` and `:face`.  The latter 
will be used to set the text foreground and background colors on the badge.  
The former is a string name from the  [...]
+
+`kind-prefix-default-face`: A face from which background color will be taken 
and blended with the `:face` foreground color in the mapping table to create a 
custom background color.  If not set, the frame default background will be used 
for this purpose.  Similarly, the foreground color for this face, if set, will 
be used if a `:face` foreground is missing from the mapping. 
+
+`kind-prefix-blend-frac`: The fractional blend between custom badge
+`:face` foreground and background (see above) color to use as a custom
+background for each badge.  A value of 0.0 simply replicates the
+background color.  Values should likely stay below 0.3 or so.
diff --git a/kind-prefix.el b/kind-prefix.el
index c6b98cb..32a6399 100644
--- a/kind-prefix.el
+++ b/kind-prefix.el
@@ -10,14 +10,16 @@
 
 ;;; Commentary:
 
-;; This package adds a prefix based on :company-kind for compatible
-;; completion UI's which utilize completion-in-region.  The "kind"
-;; prefix is typically used for differentiating variables, functions,
-;; etc. in completion results.  It works by creating and setting into
-;; `completion-extra-properties' a custom affixation-function.  This
-;; function creates and caches a short-text or icon-based "badge" for
-;; the kind of the candidate.  Icons are by default from the
-;; "material" library provided by svg-lib, which is required.
+;; kind-prefix-mode adds a prefix badge based on :company-kind for
+;; compatible completion UI's utilizing completion-in-region.  The
+;; "kind" prefix is typically used for differentiating variables,
+;; functions, etc. among completion results.  It works by creating and
+;; setting into `completion-extra-properties' a custom
+;; affixation-function.  This function creates, styles, and caches a
+;; short-text or icon-based "badge" representing the kind of the
+;; candidate.  Icons are by default loaded from the "material" library
+;; provided by svg-lib, which is required (unless only short-text
+;; badges are desired, see `kind-prefix-use-icons').
 
 ;; kind-prefix is free software: you can redistribute it
 ;; and/or modify it under the terms of the GNU General Public License