Add some documentation for vyos.version

1 files changed, 33 insertions, 0 deletions

diff --git a/python/vyos/version.py b/python/vyos/version.py
index b7fb04b52..383efbc1e 100644
--- a/python/vyos/version.py
+++ b/python/vyos/version.py
@@ -13,6 +13,21 @@
 # You should have received a copy of the GNU Lesser General Public
 # License along with this library.  If not, see <http://www.gnu.org/licenses/>.
 
+"""
+VyOS version data access library.
+
+VyOS stores its version data, which include the version number and some
+additional information in a JSON file. This module provides a convenient
+interface to reading it.
+
+Example of the version data dict::
+  {
+   'built_by': 'autobuild@vyos.net',
+   'build_id': '021ac2ee-cd07-448b-9991-9c68d878cddd',
+   'version': '1.2.0-rolling+201806200337',
+   'built_on': 'Wed 20 Jun 2018 03:37 UTC'
+  }
+"""
 
 import os
 import json
@@ -22,11 +37,29 @@ import vyos.defaults
 version_file = os.path.join(vyos.defaults.directories['data'], 'version.json')
   
 def get_version_data(file=version_file):
+    """
+    Get complete version data
+
+    Args:
+        file (str): path to the version file
+
+    Returns:
+        dict: version data
+
+    The optional ``file`` argument comes in handy in upgrade scripts
+    that need to retrieve information from images other than the running image.
+    It should not be used on a running system since the location of that file
+    is an implementation detail and may change in the future, while the interface
+    of this module will stay the same.
+    """
     with open(file, 'r') as f:
         version_data = json.load(f)
     return version_data
 
 def get_version(file=None):
+    """
+    Get the version number
+    """
     version_data = None
     if file:
         version_data = get_version_data(file=file)