From 88ad5044ae090205a8104cec6740add42188c4ac Mon Sep 17 00:00:00 2001
From: Tomas Kopecek <tkopecek@redhat.com>
Date: Oct 23 2020 07:06:29 +0000
Subject: PR#2509: doc: api docs


Merges #2509
https://pagure.io/koji/pull-request/2509

Fixes: #2110
https://pagure.io/koji/issue/2110
Missing API documentation #3

---

diff --git a/hub/kojihub.py b/hub/kojihub.py
index 6aa76c5..0776f28 100644
--- a/hub/kojihub.py
+++ b/hub/kojihub.py
@@ -10265,6 +10265,7 @@ class RootExports(object):
         return make_task('image', [name, version, arches, target, inst_tree, opts], **taskOpts)
 
     def hello(self, *args):
+        """Simple testing call returning a string"""
         return "Hello World"
 
     def fault(self):
@@ -10293,9 +10294,11 @@ class RootExports(object):
         return bool(context.opts.get('EnableWin'))
 
     def showSession(self):
+        """Return string representation of session for current user"""
         return "%s" % context.session
 
     def getSessionInfo(self):
+        """Return session info for current user"""
         if not context.session.logged_in:
             return None
         return context.session.session_data
diff --git a/koji/auth.py b/koji/auth.py
index b8091cc..3f169a5 100644
--- a/koji/auth.py
+++ b/koji/auth.py
@@ -748,6 +748,15 @@ def get_user_data(user_id):
 
 
 def login(*args, **opts):
+    """Create a login session with plain user/password credentials.
+
+    :param str user: username
+    :param str password: password
+    :param dict opts: curently can contain only 'host_ip' key for overriding client IP address
+
+    :returns dict: session info
+    """
+
     return context.session.login(*args, **opts)
 
 
@@ -756,18 +765,29 @@ def krbLogin(*args, **opts):
 
 
 def sslLogin(*args, **opts):
+    """Login via SSL certificate
+
+    :param str proxyuser: proxy username
+    :returns dict: session info
+    """
     return context.session.sslLogin(*args, **opts)
 
 
 def logout():
+    """expire a login session"""
     return context.session.logout()
 
 
 def subsession():
+    """Create a subsession"""
     return context.session.subsession()
 
 
 def logoutChild(session_id):
+    """expire a subsession
+
+    :param int subsession_id: subsession ID (for current session)
+    """
     return context.session.logoutChild(session_id)