-/*
- * called to reserve object in the pool
- * return codes:
- * ENOSPC - no space on corresponded OST
- * EAGAIN - precreation is in progress, try later
- * EIO - no access to OST
+/**
+ * Reserve object in precreate pool
+ *
+ * When the caller wants to create a new object on this target (target
+ * represented by the given OSP), it should declare this intention using
+ * a regular ->dt_declare_create() OSD API method. Then OSP will be trying
+ * to reserve an object in the existing precreated pool or wait up to
+ * obd_timeout for the available object to appear in the pool (a dedicated
+ * thread will be doing real precreation in background). The object can be
+ * consumed later with osp_precreate_get_fid() or be released with call to
+ * lu_object_put(). Notice the function doesn't reserve a specific ID, just
+ * some ID. The actual ID assignment happen in osp_precreate_get_fid().
+ * If the space on the target is short and there is a pending object destroy,
+ * then the function forces local commit to speedup space release (see
+ * osp_sync.c for the details).
+ *
+ * \param[in] env LU environment provided by the caller
+ * \param[in] d OSP device
+ *
+ * \retval 0 on success
+ * \retval -ENOSPC when no space on OST
+ * \retval -EAGAIN try later, slow precreation in progress
+ * \retval -EIO when no access to OST