From 42b3d596ea1fa574e945ea5ca99b3e1e37105ae1 Mon Sep 17 00:00:00 2001
From: Mike McLean <mikem@redhat.com>
Date: Mar 06 2018 17:26:43 +0000
Subject: update listBuilds docstring


---

diff --git a/hub/kojihub.py b/hub/kojihub.py
index eec9445..0f135cb 100644
--- a/hub/kojihub.py
+++ b/hub/kojihub.py
@@ -9512,29 +9512,40 @@ class RootExports(object):
                    volumeID=None, source=None,
                    createdBefore=None, createdAfter=None,
                    completeBefore=None, completeAfter=None, type=None, typeInfo=None, queryOpts=None):
-        """List package builds.
-        If packageID is specified, restrict the results to builds of the specified package.
-        If userID is specified, restrict the results to builds owned by the given user.
-        If taskID is specfied, restrict the results to builds with the given task ID.  If taskID is -1,
-           restrict the results to builds with a non-null taskID.
-        If volumeID is specified, restrict the results to builds stored on that volume
-        If source is specified, restrict the results to builds with given
-        CVS source. Source could be given as 'glob' string.
-        One or more of packageID, userID, volumeID, and taskID may be specified.
-        If prefix is specified, restrict the results to builds whose package name starts with that
-        prefix.
-        If createdBefore and/or createdAfter are specified, restrict the results to builds whose
-        creation_time is before and/or after the given time.
-        If completeBefore and/or completeAfter are specified, restrict the results to builds whose
-        completion_time is before and/or after the given time.
-        The time may be specified as a floating point value indicating seconds since the Epoch (as
-        returned by time.time()) or as a string in ISO format ('YYYY-MM-DD HH24:MI:SS').
-        If type is not None, only list builds of the associated type.  Currently the supported types are 'maven' and 'win'.
-        if typeInfo is not None, only list builds with matching type-specific info.  Must be used in conjunction with
-           the type parameter.
-             Currently the only supported type is 'maven', and typeInfo is a dict containing
-             one or more of group_id, artifact_id, and/or version.  Output will be restricted to builds with
-             matching Maven metadata.
+        """Return a list of builds that match the given parameters
+
+        Filter parameters
+            - packageID: only builds of the specified package (numeric id)
+            - userID: only builds owned by the given user (numeric id)
+            - taskID: only builds with the given task ID
+                If taskID is -1, only builds with a non-null task id
+            - volumeID: only builds stored on the given volume (numeric id)
+            - source: only builds where the source field matches (glob pattern)
+            - prefix: only builds whose package name starts with that prefix
+            - state: only builds in the given state (numeric value)
+
+        Timestamp filter parameters
+            - these limit the results to builds where the corresponding
+                timestamp is before or after the given time
+            - the time value may be specified as seconds since the epoch or
+                in ISO format ('YYYY-MM-DD HH24:MI:SS')
+            - filters for creation_time:
+                - createdBefore
+                - createdAfter
+            - filters for completion_time:
+                - completeBefore
+                - completeAfter
+
+        Build type parameters:
+            - type: only builds of the given btype (such as maven or image)
+            - typeInfo: only builds with matching type-specific info (given
+                as a dictionary). Can only be used in conjunction with the
+                type parameter. Only limited types are supported.
+
+                For type=maven, the provided group_id, artifact_id, and/or version
+                fields are matched
+
+                For type=win, the provided platform fields are matched
 
         Returns a list of maps.  Each map contains the following keys:
 
@@ -9560,6 +9571,7 @@ class RootExports(object):
           - completion_time
           - completion_ts
           - task_id
+          - extra
 
         If type == 'maven', each map will also contain the following keys:
 
@@ -9567,6 +9579,10 @@ class RootExports(object):
           - maven_artifact_id
           - maven_version
 
+        If type == 'win', each map will also contain the following key:
+
+            - platform
+
         If no builds match, an empty list is returned.
         """
         fields = [('build.id', 'build_id'), ('build.version', 'version'), ('build.release', 'release'),