- * After this function succeeds, @ref ready should be non-0. As well as
- * opening the audio device, this function is responsible for reconfiguring
- * if it necessary to cope with different samples formats (for backends that
- * don't demand a single fixed sample format for the lifetime of the server).
+ * On input @ref device_state may be anything. If it is @ref
+ * device_open then the device is already open but might be using
+ * the wrong sample format. The device should be reconfigured to
+ * use the right sample format.
+ *
+ * If it is @ref device_error then a retry is underway and an
+ * attempt to recover or re-open the device (with the right sample
+ * format) should be made.
+ *
+ * If it is @ref device_closed then the device should be opened with
+ * the right sample format.
+ *
+ * If the @ref FIXED_FORMAT flag is not set then @ref device_format
+ * must be set on success.
+ *
+ * Some devices are effectively always open and have no error state,
+ * in which case this callback can be NULL. In this case @ref
+ * FIXED_FORMAT must be set. Note that @ref device_state still
+ * switches between @ref device_open and @ref device_closd in this
+ * case.