Use versionadded and versionchanged in doc

Document in which version new types and functions were added using
".. versionadded:: x.y". Document changes using
".. versionchanged:: x.y."

For watchdog module, add the versionadded tag in the module top
docstring, not on each type/function.

Add docstring to ssh_execute().

I used "git blame" + "git tag --contains=SHA1" to find these version,
and then I checked manually each version.

Change-Id: I56a7d8a4335833e9b49eedab026d20adfeedf942

oslo_concurrency/fixture/lockutils.py

@@ -68,6 +68,8 @@ class ExternalLockFixture(fixtures.Fixture):
 
     Alternatively, the useFixture call could be placed in a test class's
     setUp method to provide this functionality to all tests in the class.
+
+    .. versionadded:: 0.3
     """
     def setUp(self):
         super(ExternalLockFixture, self).setUp()

oslo_concurrency/lockutils.py

@@ -72,6 +72,8 @@ def get_lock_path(conf):
 
     :param conf: Configuration object
     :type conf: oslo_config.cfg.ConfigOpts
+
+    .. versionadded:: 1.8
     """
     _register_opts(conf)
     return conf.oslo_concurrency.lock_path
@@ -79,6 +81,10 @@ def get_lock_path(conf):
 
 InterProcessLock = fasteners.InterProcessLock
 ReaderWriterLock = fasteners.ReaderWriterLock
+"""A reader/writer lock.
+
+.. versionadded:: 0.4
+"""
 
 
 class Semaphores(object):
@@ -87,6 +93,8 @@ class Semaphores(object):
     This collection internally uses a weak value dictionary so that when a
     semaphore is no longer in use (by any threads) it will automatically be
     removed from this container by the garbage collector.
+
+    .. versionadded:: 0.3
     """
 
     def __init__(self):
@@ -191,6 +199,12 @@ def lock(name, lock_file_prefix=None, external=False, lock_path=None,
         active threads.
 
     :param delay: Delay between acquisition attempts (in seconds).
+
+    .. versionchanged:: 0.2
+       Added *do_log* optional parameter.
+
+    .. versionchanged:: 0.3
+       Added *delay* and *semaphores* optional parameters.
     """
     int_lock = internal_lock(name, semaphores=semaphores)
     with int_lock:
@@ -234,6 +248,9 @@ def synchronized(name, lock_file_prefix=None, external=False, lock_path=None,
            ...
 
     This way only one of either foo or bar can be executing at a time.
+
+    .. versionchanged:: 0.3
+       Added *delay* and *semaphores* optional parameter.
     """
 
     def wrap(f):

oslo_concurrency/processutils.py

@@ -99,7 +99,10 @@ def _subprocess_setup(on_preexec_fn):
 
 @enum.unique
 class LogErrors(enum.IntEnum):
-    """Enumerations that affect if stdout and stderr are logged on error."""
+    """Enumerations that affect if stdout and stderr are logged on error.
+
+    .. versionadded:: 2.7
+    """
 
     #: No logging on errors.
     DEFAULT = 0
@@ -190,6 +193,20 @@ def execute(*cmd, **kwargs):
                             receiving unknown arguments
     :raises:                :class:`ProcessExecutionError`
     :raises:                :class:`OSError`
+
+    .. versionchanged:: 1.5
+       Added *cwd* optional parameter.
+
+    .. versionchanged:: 1.9
+       Added *binary* optional parameter. On Python 3, *stdout* and *stdout*
+       are now returned as Unicode strings by default, or bytes if *binary* is
+       true.
+
+    .. versionchanged:: 2.1
+       Added *on_execute* and *on_completion* optional parameters.
+
+    .. versionchanged:: 2.3
+       Added *preexec_fn* optional parameter.
     """
 
     cwd = kwargs.pop('cwd', None)
@@ -373,6 +390,11 @@ def trycmd(*args, **kwargs):
 def ssh_execute(ssh, cmd, process_input=None,
                 addl_env=None, check_exit_code=True,
                 binary=False):
+    """Run a command through SSH.
+
+    .. versionchanged:: 1.9
+       Added *binary* optional parameter.
+    """
     sanitized_cmd = strutils.mask_password(cmd)
     LOG.debug('Running cmd (SSH): %s', sanitized_cmd)
     if addl_env:

oslo_concurrency/watchdog.py

@@ -12,6 +12,12 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
+"""
+Watchdog module.
+
+.. versionadded:: 0.4
+"""
+
 import contextlib
 import logging
 import threading