From eadf0bd2872c1f662d107dfdb608496ebb34590d Mon Sep 17 00:00:00 2001
From: Mikolaj Izdebski <mizdebsk@redhat.com>
Date: Jan 22 2019 20:19:14 +0000
Subject: Add API docs


---

diff --git a/sidetag_hub.py b/sidetag_hub.py
index aff4604..b9ca99a 100644
--- a/sidetag_hub.py
+++ b/sidetag_hub.py
@@ -32,10 +32,23 @@ def insert(table, **kwargs):
 
 @export
 def createSideTag(base_tag):
+    """
+    Create a side tag.
+    Options:
+    - base_tag: name or ID of base tag
+    """
+
+    # Any logged-in user is able to request creation of side tags,
+    # as long the request meets the policy.
     context.session.assertLogin()
+
     base_tag = get_tag(base_tag, strict=True)
+
+    # Policy is a very flexible mechanism, that can restrict for which
+    # tags sidetags can be created, or which users can create sidetags etc.
     assert_policy('sidetag', {'tag' : base_tag['id']})
 
+    # event_id is just used a unique value that makes sidetags names unique
     event_id = _singleValue("SELECT get_event()")
     sidetag_name = '{}-side-{}'.format(base_tag['name'], event_id)
     sidetag_id = get_tag_id(sidetag_name, create=True)