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 base64 module, add the versionadded tag in the module top
docstring, not on each type/function.

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

Change-Id: I4a891b18064fe7b857a79c57030ff31f7a0370b4

oslo_serialization/base64.py

@@ -13,6 +13,12 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+"""
+Utilities to encode and decode Base64.
+
+.. versionadded:: 1.10
+"""
+
 from __future__ import absolute_import
 
 import base64

oslo_serialization/jsonutils.py

@@ -86,6 +86,12 @@ def to_primitive(value, convert_instances=False, convert_datetime=True,
     track the depth of the object inspections and don't go too deep.
 
     Therefore, ``convert_instances=True`` is lossy ... be aware.
+
+    .. versionchanged:: 1.3
+       Support UUID encoding.
+
+    .. versionchanged:: 1.6
+       Dictionary keys are now also encoded.
     """
     # handle obvious types first - order of basic types determined by running
     # full tests on nova project, resulting in the following counts:
@@ -178,7 +184,8 @@ def dumps(obj, default=to_primitive, **kwargs):
     """Serialize ``obj`` to a JSON formatted ``str``.
 
     :param obj: object to be serialized
-    :param default: function that returns a serializable version of an object
+    :param default: function that returns a serializable version of an object,
+                    :func:`to_primitive` is used by default.
     :param kwargs: extra named parameters, please see documentation \
     of `json.dumps <https://docs.python.org/2/library/json.html#basic-usage>`_
     :returns: json formatted string
@@ -195,13 +202,14 @@ def dump_as_bytes(obj, default=to_primitive, encoding='utf-8', **kwargs):
     """Serialize ``obj`` to a JSON formatted ``bytes``.
 
     :param obj: object to be serialized
-    :param default: function that returns a serializable version of an object
+    :param default: function that returns a serializable version of an object,
+                    :func:`to_primitive` is used by default.
     :param encoding: encoding used to encode the serialized JSON output
     :param kwargs: extra named parameters, please see documentation \
     of `json.dumps <https://docs.python.org/2/library/json.html#basic-usage>`_
     :returns: json formatted string
 
-    .. versionadded:: 2.0
+    .. versionadded:: 1.10
     """
     serialized = dumps(obj, default=default, **kwargs)
     if isinstance(serialized, six.text_type):
@@ -215,11 +223,15 @@ def dump(obj, fp, *args, **kwargs):
 
     :param obj: object to be serialized
     :param fp: a ``.write()``-supporting file-like object
-    :param default: function that returns a serializable version of an object
+    :param default: function that returns a serializable version of an object,
+                    :func:`to_primitive` is used by default.
     :param args: extra arguments, please see documentation \
     of `json.dump <https://docs.python.org/2/library/json.html#basic-usage>`_
     :param kwargs: extra named parameters, please see documentation \
     of `json.dump <https://docs.python.org/2/library/json.html#basic-usage>`_
+
+    .. versionchanged:: 1.3
+       The *default* parameter now uses :func:`to_primitive` by default.
     """
     default = kwargs.get('default', to_primitive)
     if is_simplejson:

oslo_serialization/msgpackutils.py

@@ -23,6 +23,8 @@ This module provides a few things:
    wrapper will automatically use
    the :py:attr:`~oslo_serialization.msgpackutils.default_registry` for
    you if needed.
+
+.. versionadded:: 1.3
 '''
 
 
@@ -63,6 +65,8 @@ class HandlerRegistry(object):
     it to a list.
 
     This may be fixed in: https://github.com/msgpack/msgpack-python/pull/100
+
+    .. versionadded:: 1.5
     """
 
     # Applications can assign 0 to 127 to store
@@ -309,11 +313,17 @@ This registry has msgpack extensions for the following:
 * ``set`` and ``frozenset`` container(s).
 * ``netaddr.IPAddress`` objects (only if ``netaddr`` is importable).
 * ``xmlrpclib.DateTime`` datetime objects.
+
+.. versionadded:: 1.5
 """
 
 
 def load(fp, registry=None):
-    """Deserialize ``fp`` into a Python object."""
+    """Deserialize ``fp`` into a Python object.
+
+    .. versionchanged:: 1.5
+       Added *registry* parameter.
+    """
     if registry is None:
         registry = default_registry
     # NOTE(harlowja): the reason we can't use the more native msgpack functions
@@ -324,7 +334,11 @@ def load(fp, registry=None):
 
 
 def dump(obj, fp, registry=None):
-    """Serialize ``obj`` as a messagepack formatted stream to ``fp``."""
+    """Serialize ``obj`` as a messagepack formatted stream to ``fp``.
+
+    .. versionchanged:: 1.5
+       Added *registry* parameter.
+    """
     if registry is None:
         registry = default_registry
     return msgpack.pack(obj, fp,
@@ -333,7 +347,11 @@ def dump(obj, fp, registry=None):
 
 
 def dumps(obj, registry=None):
-    """Serialize ``obj`` to a messagepack formatted ``str``."""
+    """Serialize ``obj`` to a messagepack formatted ``str``.
+
+    .. versionchanged:: 1.5
+       Added *registry* parameter.
+    """
     if registry is None:
         registry = default_registry
     return msgpack.packb(obj,
@@ -342,7 +360,11 @@ def dumps(obj, registry=None):
 
 
 def loads(s, registry=None):
-    """Deserialize ``s`` messagepack ``str`` into a Python object."""
+    """Deserialize ``s`` messagepack ``str`` into a Python object.
+
+    .. versionchanged:: 1.5
+       Added *registry* parameter.
+    """
     if registry is None:
         registry = default_registry
     ext_hook = functools.partial(_unserializer, registry)