[_120] doc string for list_tickets

Author: d-w-moore

irods/ticket.py

@@ -29,9 +29,22 @@ def get_epoch_seconds(utc_timestamp):
 
 
 def list_tickets(session, all=True):
+    """
+    Enumerates (via GenQuery1) all tickets visible by, or owned by, the current user.
+
+    Args:
+        session: An iRODSSession object for use in the query.
+        all: True if a comprehensive list is desired; otherwise only those
+            tickets owned by the calling user.
+
+    Returns:
+        An iterator over a range of ticket objects.
+    """
     query = session.query(TicketQuery.Ticket)
     if not all:
-        query = query.filter(TicketQuery.Ticket.user_id == session.users.get(session.username).id)
+        query = query.filter(
+            TicketQuery.Ticket.user_id == session.users.get(session.username).id
+        )
     yield from query