From 1e74f1297b7d4521cd6e27323b827f14ea0fec12 Mon Sep 17 00:00:00 2001
From: Marc Abramowitz <marc@marc-abramowitz.com>
Date: Sat, 12 May 2012 22:44:00 -0700
Subject: [PATCH] Improved documentation for the brew module
 (salt/modules/brew.py)

---
 salt/modules/brew.py | 47 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 41 insertions(+), 6 deletions(-)

diff --git a/salt/modules/brew.py b/salt/modules/brew.py
index 7a0ae6780a..de98cdddbb 100644
--- a/salt/modules/brew.py
+++ b/salt/modules/brew.py
@@ -13,9 +13,14 @@ def __virtual__():
 
 def list_pkgs(*args):
     '''
-    Do brew list
-    '''
+    List the packages currently installed in a dict::
 
+        {'<package_name>': '<version>'}
+
+    CLI Example::
+
+        salt '*' pkg.list_pkgs
+    '''
     cmd = 'brew list --versions {0}'.format(' '.join(args))
 
     result_dict = {}
@@ -44,9 +49,14 @@ def version(name):
 
 def remove(pkgs):
     '''
-    Do brew uninstall
-    '''
+    Removes packages with ``brew uninstall``
 
+    Return a list containing the removed packages:
+
+    CLI Example::
+
+        salt '*' pkg.remove <package,package,package>
+    '''
     formulas = ' '.join(pkgs.split(','))
     cmd = '/usr/local/bin/brew uninstall {0}'.format(formulas)
 
@@ -55,9 +65,20 @@ def remove(pkgs):
 
 def install(pkgs):
     '''
-    Do brew install
-    '''
+    Install the passed package(s) with ``brew install``
 
+    pkgs
+        The names of the packages to be installed
+
+    Return a dict containing the new package names and versions::
+
+        {'<package>': {'old': '<old-version>',
+                   'new': '<new-version>']}
+
+    CLI Example::
+
+        salt '*' pkg.install 'package package package'
+    '''
     if ',' in pkgs:
         pkgs = pkgs.split(',')
     else:
@@ -76,10 +97,24 @@ def install(pkgs):
 
 
 def list_upgrades():
+    '''
+    Check whether or not an upgrade is available for all packages
+
+    CLI Example::
+
+        salt '*' pkg.list_upgrades
+    '''
     cmd = '/usr/local/bin/brew outdated'
 
     return __salt__['cmd.run'](cmd).splitlines()
 
 
 def upgrade_available(pkg):
+    '''
+    Check whether or not an upgrade is available for a given package
+
+    CLI Example::
+
+        salt '*' pkg.upgrade_available <package name>
+    '''
     return pkg in list_upgrades()