Add documentation.

salt/modules/macports.py

@@ -1,6 +1,33 @@
 # -*- coding: utf-8 -*-
 '''
-Support for MacPorts under MacOSX
+Support for MacPorts under Mac OSX.
+
+This module has some caveats.
+
+1. Updating the database of available ports is quite resource-intensive.
+However, `refresh=True` is the default for all operations that need an 
+up-to-date copy of available ports.  Consider `refresh=False` when you are
+sure no db update is needed.
+
+2. In some cases MacPorts doesn't always realize when another copy of itself
+is running and will gleefully tromp all over the available ports database.
+This makes MacPorts behave in undefined ways until a fresh complete
+copy is retrieved.
+
+Because of 1 and 2 it is possible to get the salt-minion into a state where
+`salt mac-machine pkg./something/` won't want to return.  Use
+
+`salt-run jobs.active`
+
+on the master to check for potentially long-running calls to `port`.
+
+Finally, ports database updates are always handled with `port selfupdate`
+as opposed to `port sync`.  This makes sense in the MacPorts user commmunity
+but may confuse experienced Linux admins as Linux package managers
+don't upgrade the packaging software when doing a package database update.
+In other words `salt mac-machine pkg.refresh_db` is more like
+`apt-get update; apt-get upgrade dpkg apt-get` than simply `apt-get update`.
+
 '''
 
 # Import python libs
@@ -14,7 +41,6 @@ import salt.utils
 log = logging.getLogger(__name__)
 
 LIST_ACTIVE_ONLY = True
-
 __virtualname__ = 'pkg'