Clarify docs, add depth option

salt/modules/cmdmod.py

@@ -2619,13 +2619,27 @@ def powershell(cmd,
         saltenv='base',
         use_vt=False,
         password=None,
+        depth=None,
         **kwargs):
     '''
-    Execute the passed PowerShell command and return the output as a string.
+    Execute the passed PowerShell command and return the output as a dictionary.
+
+    Other ``cmd.*`` functions return the raw text output of the command. This
+    function appends ``| ConvertTo-JSON`` to the command and then parses the
+    JSON into a Python dictionary. If you want the raw textual result of your
+    PowerShell command you should use ``cmd.run`` with the ``shell=powershell``
+    option.
+
+    For example:
+
+    .. code-block:: bash
+
+        salt '*' cmd.run '$PSVersionTable.CLRVersion' shell=powershell
+        salt '*' cmd.run 'Get-NetTCPConnection' shell=powershell
 
     .. versionadded:: 2016.3.0
 
-    .. warning ::
+    .. warning::
 
         This passes the cmd argument directly to PowerShell
         without any further processing! Be absolutely sure that you
@@ -2635,6 +2649,16 @@ def powershell(cmd,
     Note that ``env`` represents the environment variables for the command, and
     should be formatted as a dict, or a YAML string which resolves to a dict.
 
+    In addition to the normal ``cmd.run`` parameters, this command offers the
+    ``depth`` parameter to change the Windows default depth for the
+    ``ConvertTo-JSON`` powershell command. The Windows default is 2. If you need
+    more depth, set that here.
+
+    .. note::
+        For some commands, setting the depth to a value greater than 4 greatly
+        increases the time it takes for the command to return and in many cases
+        returns useless data.
+
     :param str cmd: The powershell command to run.
 
     :param str cwd: The current working directory to execute the command in
@@ -2727,6 +2751,12 @@ def powershell(cmd,
 
     :param str saltenv: The salt environment to use. Default is 'base'
 
+    :param int depth: The number of levels of contained objects to be included.
+        Default is 2.
+
+    :returns:
+        :dict: A dictionary of data returned by the powershell command.
+
     CLI Example:
 
     .. code-block:: powershell
@@ -2739,7 +2769,9 @@ def powershell(cmd,
         python_shell = True
 
     # Append PowerShell Object formatting
-    cmd = '{0} | ConvertTo-Json -Depth 32'.format(cmd)
+    cmd += ' | ConvertTo-JSON'
+    if depth is not None:
+        cmd += ' -Depth {0}'.format(depth)
 
     # Retrieve the response, while overriding shell with 'powershell'
     response = run(cmd,