                     :time-rest (- time-rest interval)
                     :times (inc times)))))))
 
-(defn wait-exists [driver q & [opt]]
+(defn wait-exists
+  "Waits until an element exists on a page (bur may not be visible though).
+
+  Arguments:
+
+  - `driver`: a driver instance;
+  - `q`: a query term (see `query`);
+  - `opt`: a map of options (see `wait-predicate`)."
+
+  [driver q & [opt]]
   (wait-predicate #(exists? driver q) opt))
 
-(defn wait-absent [driver q & [opt]]
+(defn wait-absent
+  "Waits until an element is absent.
+
+  Arguments:
+
+  - `driver`: a driver instance;
+  - `q`: a query term (see `query`);
+  - `opt`: a map of options (see `wait-predicate`)."
+
+  [driver q & [opt]]
   (let [message (format "Wait for %s element is absent" q)]
     (wait-predicate #(absent? driver q)
                     (assoc opt :message message))))
 
-(defn wait-visible [driver q & [opt]]
+(defn wait-visible
+  "Waits until an element presents and is visible.
+
+  Arguments:
+
+  - `driver`: a driver instance;
+  - `q`: a query term (see `query`);
+  - `opt`: a map of options (see `wait-predicate`)."
+
+  [driver q & [opt]]
   (let [message (format "Wait for %s element is visible" q)]
     (wait-predicate #(visible? driver q)
                     (assoc opt :message message))))
 
-(defn wait-invisible [driver q & [opt]]
+(defn wait-invisible
+  "Waits until an element presents but not visible.
+
+  Arguments:
+
+  - `driver`: a driver instance;
+  - `q`: a query term (see `query`);
+  - `opt`: a map of options (see `wait-predicate`)."
+
+  [driver q & [opt]]
   (wait-predicate #(invisible? driver q) opt))
 
-(defn wait-enabled [driver q & [opt]]
+(defn wait-enabled
+  "Waits until an element is enabled (usually an input element).
+
+  Arguments:
+
+  - `driver`: a driver instance;
+  - `q`: a query term (see `query`);
+  - `opt`: a map of options (see `wait-predicate`)."
+
+  [driver q & [opt]]
   (wait-predicate #(enabled? driver q) opt))
 
-(defn wait-disabled [driver q & [opt]]
+(defn wait-disabled
+  "Waits until an element is disabled (usually an input element).
+
+  Arguments:
+
+  - `driver`: a driver instance;
+  - `q`: a query term (see `query`);
+  - `opt`: a map of options (see `wait-predicate`)."
+
+  [driver q & [opt]]
   (wait-predicate #(disabled? driver q) opt))
 
-(defn wait-has-alert [driver & [opt]]
+(defn wait-has-alert
+  "Waits until an alert dialog appears on the screen.
+
+  Arguments:
+
+  - `driver`: a driver instance;
+  - `q`: a query term (see `query`);
+  - `opt`: a map of options (see `wait-predicate`)."
+
+  [driver & [opt]]
   (wait-predicate #(has-alert? driver) opt))
 
 (defn wait-has-text
+  "Waits until an element has text anywhere inside it (including inner HTML).
+
+  Arguments:
+
+  - `driver`: a driver instance;
+  - `q`: a query term (see `query`);
+  - `text`: a string to search;
+  - `opt`: a map of options (see `wait-predicate`)."
+
   [driver q text & [opt]]
   (let [message (format "Wait for %s element has text %s"
                         q text)]
     (wait-predicate #(has-text? driver q text)
                     (assoc opt :message message))))
 
-(defn wait-has-class [driver q class & [opt]]
+(defn wait-has-class
+  "Waits until an element has specific class.
+
+  Arguments:
+
+  - `driver`: a driver instance;
+  - `q`: a query term (see `query`);
+  - `class`: a class to search as string;
+  - `opt`: a map of options (see `wait-predicate`)."
+
+  [driver q class & [opt]]
   (wait-predicate #(has-class? driver q class) opt))
 
 (defn wait-running [driver & [opt]]

;;

(defn click-visible
  [driver q & [opt]]
  (doto driver
    (wait-visible q opt)

  `(when-not (~predicate)
     ~@body))

(defmacro when-not-chrome
  "Executes the body only if a browser is NOT Chrome."
  [driver & body]
  `(when-not-predicate #(chrome? ~driver) ~@body))

(defmacro when-not-phantom
  "Executes the body only if a browser is NOT Phantom.js."
  [driver & body]
  `(when-not-predicate #(phantom? ~driver) ~@body))

(defmacro when-not-firefox
  "Executes the body only if a browser is NOT Firefox."
  [driver & body]
  `(when-not-predicate #(firefox? ~driver) ~@body))

(defmacro when-not-safari
  "Executes the body only if a browser is NOT Safari."
  [driver & body]
  `(when-not-predicate #(safari? ~driver) ~@body))

(defmacro when-predicate
  "Executes the body only if a predicate returns true."
  [predicate & body]
  `(when (~predicate)
     ~@body))

