diff --git a/README.md b/README.md
index 43f502c..fe0d339 100644
--- a/README.md
+++ b/README.md
@@ -13,10 +13,12 @@ See [issues](zsh-completions/issues) for details on each completion definition.
 
 Usage
 -----
-Drop the scripts in a directory included in your `$fpath`.
+Drop the scripts in a directory included in your `$fpath`, for example:
+
+    git clone git://github.com/zsh-users/zsh-completions.git
+    fpath=(path/to/zsh-completions $fpath)
 
 
 License
 -------
 See each file for license details.
-
diff --git a/_ack b/_ack
index 3683f92..91e5314 100644
--- a/_ack
+++ b/_ack
@@ -25,18 +25,18 @@
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 # ------------------------------------------------------------------------------
+# Description
+# -----------
+#
+#  Completion script for ack (http://betterthangrep.com).
+#
+# ------------------------------------------------------------------------------
 # Authors
 # -------
 #
 #  * Julien Nicoulaud <julien.nicoulaud@gmail.com>
 #
 # ------------------------------------------------------------------------------
-# Status
-# ------
-#
-#  See FIXME and TODO tags.
-#
-# ------------------------------------------------------------------------------
 # -*- mode: zsh; sh-indentation: 2; indent-tabs-mode: nil; sh-basic-offset: 2; -*-
 # vim: ft=zsh sw=2 ts=2 et
 # ------------------------------------------------------------------------------
@@ -147,7 +147,7 @@ _ack_colors() {
 _ack_type_defs() {
   local ret=1
   if compset -P '*='; then
-    _message -e extensions 'extensions list' && ret=0 // TODO Provide the extensions of the files in the current dir here ?
+    _message -e extensions 'extensions list' && ret=0 # TODO Provide the extensions of the files in the current dir here ?
   else
     _message -e type-name 'type name' && ret=0
   fi
diff --git a/_mvn b/_mvn
index 0d6c9ec..6f6512a 100644
--- a/_mvn
+++ b/_mvn
@@ -25,18 +25,20 @@
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 # ------------------------------------------------------------------------------
+# Description
+# -----------
+#
+#  Completion script for Maven (http://maven.apache.org).
+#
+#  Status: Incomplete, see FIXME and TODO tags.
+#
+# ------------------------------------------------------------------------------
 # Authors
 # -------
 #
 #  * Julien Nicoulaud <julien.nicoulaud@gmail.com>
 #
 # ------------------------------------------------------------------------------
-# Status
-# ------
-#
-#  See FIXME and TODO tags.
-#
-# ------------------------------------------------------------------------------
 # How to tweak
 # ------------
 #
diff --git a/_pip b/_pip
index 20fe3f2..1bfaf86 100644
--- a/_pip
+++ b/_pip
@@ -1,4 +1,21 @@
 #compdef pip
+# ------------------------------------------------------------------------------
+# Description
+# -----------
+#
+#  Completion script for pip (http://pypi.python.org/pypi/pip).
+#
+# ------------------------------------------------------------------------------
+# Authors
+# -------
+#
+#  * Dmitry Gladkov (https://github.com/dgladkov)
+#
+# ------------------------------------------------------------------------------
+# -*- mode: zsh; sh-indentation: 2; indent-tabs-mode: nil; sh-basic-offset: 2; -*-
+# vim: ft=zsh sw=2 ts=2 et
+# ------------------------------------------------------------------------------
+
 
 local subcmds
 
diff --git a/_play b/_play
index ec77008..91890c0 100644
--- a/_play
+++ b/_play
@@ -25,18 +25,20 @@
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 # ------------------------------------------------------------------------------
+# Description
+# -----------
+#
+#  Completion script for Play! framework (http://www.playframework.org).
+#
+#  Status: Incomplete, see FIXME and TODO tags.
+#
+# ------------------------------------------------------------------------------
 # Authors
 # -------
 #
 #  * Julien Nicoulaud <julien.nicoulaud@gmail.com>
 #
 # ------------------------------------------------------------------------------
-# Status
-# ------
-#
-#  See FIXME and TODO tags.
-#
-# ------------------------------------------------------------------------------
 # -*- mode: zsh; sh-indentation: 2; indent-tabs-mode: nil; sh-basic-offset: 2; -*-
 # vim: ft=zsh sw=2 ts=2 et
 # ------------------------------------------------------------------------------