Improve pkgrepo docs

Also deprecate the refresh_db argument in aptpkg.mod_repo (and the
pkgrepo states), in favor of the widely used "refresh" argument.

salt/modules/aptpkg.py

@@ -2147,44 +2147,44 @@ def mod_repo(repo, saltenv='base', **kwargs):
 
     The following options are available to modify a repo definition:
 
-        architectures
-            a comma separated list of supported architectures, e.g. ``amd64``
-            If this option is not set, all architectures (configured in the
-            system) will be used.
+    architectures
+        A comma-separated list of supported architectures, e.g. ``amd64`` If
+        this option is not set, all architectures (configured in the system)
+        will be used.
 
-        comps
-            a comma separated list of components for the repo, e.g. ``main``
+    comps
+        A comma separated list of components for the repo, e.g. ``main``
 
-        file
-            a file name to be used
+    file
+        A file name to be used
 
-        keyserver
-            keyserver to get gpg key from
+    keyserver
+        Keyserver to get gpg key from
 
-        keyid
-            key id to load with the keyserver argument
+    keyid
+        Key ID to load with the ``keyserver`` argument
 
-        key_url
-            URL to a GPG key to add to the APT GPG keyring
+    key_url
+        URL to a GPG key to add to the APT GPG keyring
 
-        key_text
-            GPG key in string form to add to the APT GPG keyring
+    key_text
+        GPG key in string form to add to the APT GPG keyring
 
-        consolidate
-            if ``True``, will attempt to de-dup and consolidate sources
+    consolidate : False
+        If ``True``, will attempt to de-duplicate and consolidate sources
 
-        comments
-            Sometimes you want to supply additional information, but not as
-            enabled configuration. All comments provided here will be joined
-            into a single string and appended to the repo configuration with a
-            comment marker (#) before it.
+    comments
+        Sometimes you want to supply additional information, but not as
+        enabled configuration. All comments provided here will be joined
+        into a single string and appended to the repo configuration with a
+        comment marker (#) before it.
 
-            .. versionadded:: 2015.8.9
+        .. versionadded:: 2015.8.9
 
-        .. note:: Due to the way keys are stored for APT, there is a known issue
-                where the key won't be updated unless another change is made
-                at the same time.  Keys should be properly added on initial
-                configuration.
+    .. note::
+        Due to the way keys are stored for APT, there is a known issue where
+        the key won't be updated unless another change is made at the same
+        time. Keys should be properly added on initial configuration.
 
     CLI Examples:
 
@@ -2193,6 +2193,17 @@ def mod_repo(repo, saltenv='base', **kwargs):
         salt '*' pkg.mod_repo 'myrepo definition' uri=http://new/uri
         salt '*' pkg.mod_repo 'myrepo definition' comps=main,universe
     '''
+    if 'refresh_db' in kwargs:
+        salt.utils.versions.warn_until(
+            'Neon',
+            'The \'refresh_db\' argument to \'pkg.mod_repo\' has been '
+            'renamed to \'refresh\'. Support for using \'refresh_db\' will be '
+            'removed in the Neon release of Salt.'
+        )
+        refresh = kwargs['refresh_db']
+    else:
+        refresh = kwargs.get('refresh', True)
+
     _check_apt()
     # to ensure no one sets some key values that _shouldn't_ be changed on the
     # object itself, this is just a white-list of "ok" to set properties
@@ -2225,7 +2236,7 @@ def mod_repo(repo, saltenv='base', **kwargs):
                             )
                         )
                     # explicit refresh when a repo is modified.
-                    if kwargs.get('refresh_db', True):
+                    if refresh:
                         refresh_db()
                     return {repo: out}
             else:
@@ -2429,7 +2440,7 @@ def mod_repo(repo, saltenv='base', **kwargs):
             setattr(mod_source, key, kwargs[key])
     sources.save()
     # on changes, explicitly refresh
-    if kwargs.get('refresh_db', True):
+    if refresh:
         refresh_db()
     return {
         repo: {

salt/states/pkgrepo.py

@@ -97,6 +97,7 @@ import salt.utils
 import salt.utils.files
 import salt.utils.pkg.deb
 import salt.utils.pkg.rpm
+import salt.utils.versions
 
 
 def __virtual__():
@@ -132,7 +133,7 @@ def managed(name, ppa=None, **kwargs):
 
     disabled : False
         Included to reduce confusion due to APT's use of the ``disabled``
-        argument. If this is passed for a yum/dnf/zypper-based distro, then the
+        argument. If this is passed for a YUM/DNF/Zypper-based distro, then the
         reverse will be passed as ``enabled``. For example passing
         ``disabled=True`` will assume ``enabled=False``.
 
@@ -151,7 +152,7 @@ def managed(name, ppa=None, **kwargs):
         enabled configuration. Anything supplied for this list will be saved
         in the repo configuration with a comment marker (#) in front.
 
-    Additional configuration values seen in yum repo files, such as ``gpgkey`` or
+    Additional configuration values seen in repo files, such as ``gpgkey`` or
     ``gpgcheck``, will be used directly as key-value pairs. For example:
 
     .. code-block:: yaml
@@ -258,29 +259,45 @@ def managed(name, ppa=None, **kwargs):
 
            Use either ``keyid``/``keyserver`` or ``key_url``, but not both.
 
-    consolidate
-       If set to true, this will consolidate all sources definitions to
-       the sources.list file, cleanup the now unused files, consolidate
-       components (e.g. main) for the same URI, type, and architecture
-       to a single line, and finally remove comments from the sources.list
-       file.  The consolidate will run every time the state is processed. The
-       option only needs to be set on one repo managed by salt to take effect.
+    consolidate : False
+       If set to ``True``, this will consolidate all sources definitions to the
+       sources.list file, cleanup the now unused files, consolidate components
+       (e.g. main) for the same URI, type, and architecture to a single line,
+       and finally remove comments from the sources.list file.  The consolidate
+       will run every time the state is processed. The option only needs to be
+       set on one repo managed by salt to take effect.
 
-    clean_file
-       If set to true, empty file before config repo, dangerous if use
-       multiple sources in one file.
+    clean_file : False
+       If set to ``True``, empty the file before config repo
+
+       .. note::
+           Use with care. This can be dangerous if multiple sources are
+           configured in the same file.
 
        .. versionadded:: 2015.8.0
 
-    refresh_db
-       If set to false this will skip refreshing the apt package database on
-       debian based systems.
+    refresh : True
+       If set to ``False`` this will skip refreshing the apt package database
+       on debian based systems.
+
+    refresh_db : True
+       .. deprecated:: Oxygen
+           Use ``refresh`` instead.
 
     require_in
        Set this to a list of pkg.installed or pkg.latest to trigger the
        running of apt-get update prior to attempting to install these
-       packages. Setting a require in the pkg will not work for this.
+       packages. Setting a require in the pkg state will not work for this.
     '''
+    if 'refresh_db' in kwargs:
+        salt.utils.versions.warn_until(
+            'Neon',
+            'The \'refresh_db\' argument to \'pkg.mod_repo\' has been '
+            'renamed to \'refresh\'. Support for using \'refresh_db\' will be '
+            'removed in the Neon release of Salt.'
+        )
+        kwargs['refresh'] = kwargs.pop('refresh_db')
+
     ret = {'name': name,
            'changes': {},
            'result': None,