@@ -153,6 +153,13 @@ static inline int wb_congested(struct bdi_writeback *wb, int cong_bits)
 	return wb->congested & cong_bits;
 }
 
+/* NOTE congestion_wait() and wait_iff_congested() are
+ * largely useless except as documentation.
+ * congestion_wait() will (almost) always wait for the given timeout.
+ * wait_iff_congested() will (almost) never wait, but will call
+ * cond_resched().
+ * Were possible an alternative waiting strategy should be found.
+ */
 long congestion_wait(int sync, long timeout);
 long wait_iff_congested(int sync, long timeout);
 

@@ -1023,6 +1023,11 @@ EXPORT_SYMBOL(set_bdi_congested);
  * Waits for up to @timeout jiffies for a backing_dev (any backing_dev) to exit
  * write congestion.  If no backing_devs are congested then just wait for the
  * next write to be completed.
+ *
+ * NOTE: in the current implementation, hardly any backing_devs are ever
+ * marked as congested, and write-completion is rarely reported (see calls
+ * to clear_bdi_congested).  So this should not be assumed to ever wake before
+ * the timeout.
  */
 long congestion_wait(int sync, long timeout)
 {

@@ -1054,6 +1059,10 @@ EXPORT_SYMBOL(congestion_wait);
  * The return value is 0 if the sleep is for the full timeout. Otherwise,
  * it is the number of jiffies that were still remaining when the function
  * returned. return_value == timeout implies the function did not sleep.
+ *
+ * NOTE: in the current implementation, hardly any backing_devs are ever
+ * marked as congested, and write-completion is rarely reported (see calls
+ * to clear_bdi_congested).  So this should not be assumed to sleep at all.
  */
 long wait_iff_congested(int sync, long timeout)
 {