From 1a02db13bc56e66279e936a7cca92a56cbb3dbdf Mon Sep 17 00:00:00 2001
From: Konstantin Gredeskoul <kig@reinvent.one>
Date: Sat, 7 May 2016 06:39:40 -0700
Subject: [PATCH] Adding documentation

---
 README.md       | 60 +++++++++++++++++++++++++++++++++++++++----------
 lib/search.bash | 30 ++++++++++++++++---------
 2 files changed, 68 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index bd92e849..36779e83 100644
--- a/README.md
+++ b/README.md
@@ -56,25 +56,61 @@ bash-it help plugins        # shows help for installed plugins
 ## Search
 
 If you need to quickly find out which of the plugins, aliases or completions
-are available for a specific task or an environment, you can search for 
-multiple terms related to the commands you use frequently.  Search will 
-find and output modules with the name or description matching the terms 
+are available for a specific framework, programming language, or an environment, you can _search_ for
+multiple terms related to the commands you use frequently.  Search will
+find and print out modules with the name or description matching the terms
 provided.
 
-```
-bash-it search term1 [term2] [term3]....
+#### Syntax
+
+```bash
+  bash-it search term1 [[-]term2] [[-]term3]....
 ```
 
-For example, if you are a ruby developer, you might want to enable everything 
-related to the commands such as `ruby`, `rake`, `gem`, `bundler` and `rails`. 
-Search command helps you find related modules, so that you can decide which 
+As an example, a ruby developer might want to enable everything
+related to the commands such as `ruby`, `rake`, `gem`, `bundler` and `rails`.
+Search command helps you find related modules, so that you can decide which
 of them you'd like to use:
 
+```bash
+❯ bash-it search ruby rake gem bundle irb rails
+      aliases:  bundler rails
+      plugins:  chruby chruby-auto ruby
+  completions:  bundler gem rake
 ```
-> bash-it search ruby rake gem bundle irb rails
-aliases     : bundler rails
-plugins     : chruby chruby-auto ruby
-completions : bundler gem rake
+
+Currently enabled modules will be shown in green.
+
+#### Search with Negations
+
+You can prefix a search term with a "-" to exclude it from the results. In the above
+example, if we wanted to hide `chruby` and `chruby-auto`, we could change the command as
+follows:
+
+```bash
+❯ bash-it search ruby rake gem bundle irb rails -chruby
+      aliases:  bundler rails
+      plugins:  ruby
+  completions:  bundler gem rake
+```
+
+#### Using Search to Enable or Disable Components
+
+By adding a `--enable` or `--disable` to the search command, you can automatically
+enable all modules that come up as a result of a search query. This could be quite
+handy if you like to enable a bunch of components related to the same topic.
+
+#### Disabling ASCII Color
+
+To remove non-printing non-ASCII characters responsible for the coloring of the
+search output, you can set environment variable `NO_COLOR`. Enabled components will
+then be shown with a checkmark:
+
+```bash
+❯ NO_COLOR=1 bash-it search ruby rake gem bundle irb rails -chruby
+      aliases  =>   ✓bundler ✓rails
+      plugins  =>   ✓ruby
+  completions  =>   bundler gem rake
 ```
 
 ## Your Custom scripts, aliases, themes, and functions
diff --git a/lib/search.bash b/lib/search.bash
index f5b66096..9afe3a3c 100644
--- a/lib/search.bash
+++ b/lib/search.bash
@@ -12,18 +12,28 @@
 #    Double dash indicates a command that is to be applied to the search result.
 #    At the moment only --enable and --disable are supported.
 #
-# Example:
-# ❯ bash-it search ruby rbenv rvm gem rake
-# aliases     :  bundler
-# plugins     :  chruby chruby-auto rbenv ruby rvm
-# completions :  gem rake
+# Examples:
+#    ❯ bash-it search ruby rbenv rvm gem rake
+#    aliases     :  bundler
+#    plugins     :  chruby chruby-auto rbenv ruby rvm
+#    completions :  gem rake
 
-# ❯ bash-it search ruby rbenv rvm gem rake -chruby
-# aliases     :  bundler
-# plugins     :  rbenv ruby rvm
-# completions :  gem rake
+#    ❯ bash-it search ruby rbenv rvm gem rake -chruby
+#    aliases     :  bundler
+#    plugins     :  rbenv ruby rvm
+#    completions :  gem rake
+#
+# Examples of enabling or disabling results of the search:
+#
+#    ❯ bash-it search ruby
+#    aliases  =>   bundler
+#    plugins  =>   chruby chruby-auto ruby
+#
+#    ❯ bash-it search ruby -chruby --enable
+#    aliases  =>   ✓bundler
+#    plugins  =>   ✓ruby
+#
 #
-
 _bash-it-search() {
   _about 'searches for given terms amongst bash-it plugins, aliases and completions'
   _param '1: term1'