[libvirt] [PATCH v3 2/6] storage: Add comments for backend APIs

[John Ferlan]

Just so it's clearer what to expect upon input and what types of return
values could be generated.  These were loosely copied from existing
virStorageBackendUpdateVolTargetInfoFD.

Signed-off-by: John Ferlan <jferlan at redhat.com>
---
 src/storage/storage_backend.c | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/src/storage/storage_backend.c b/src/storage/storage_backend.c
index 94b0b3f..1ee83aa 100644
--- a/src/storage/storage_backend.c
+++ b/src/storage/storage_backend.c
@@ -1389,6 +1389,14 @@ static struct diskType const disk_types[] = {
 };
 
 
+/*
+ * virStorageBackendDetectBlockVolFormatFD
+ * @target: target definition ptr of volume to update
+ * @fd: fd of storage volume to update,
+ * @readflags: unused
+ *
+ * Returns 0 for success, -1 on a legitimate error condition
+ */
 static int
 virStorageBackendDetectBlockVolFormatFD(virStorageSourcePtr target,
                                         int fd,
@@ -1578,6 +1586,17 @@ virStorageBackendVolOpen(const char *path, struct stat *sb,
     return fd;
 }
 
+/*
+ * virStorageBackendUpdateVolTargetInfo
+ * @target: target definition ptr of volume to update
+ * @withBlockVolFormat: true if caller determined a block file
+ * @openflags: various VolOpenCheckMode flags to handle errors on open
+ * @readflags: unused
+ *
+ * Returns 0 for success, -1 on a legitimate error condition, and -2
+ * if the openflags used VIR_STORAGE_VOL_OPEN_NOERROR and some sort of
+ * open error occurred. It is up to the caller to handle.
+ */
 int
 virStorageBackendUpdateVolTargetInfo(virStorageSourcePtr target,
                                      bool withBlockVolFormat,
@@ -1636,6 +1655,17 @@ virStorageBackendUpdateVolTargetInfo(virStorageSourcePtr target,
     return ret;
 }
 
+/*
+ * virStorageBackendUpdateVolInfo
+ * @vol: Pointer to a volume storage definition
+ * @withBlockVolFormat: true if the caller determined a block file
+ * @openflags: various VolOpenCheckMode flags to handle errors on open
+ * @readflags: unused
+ *
+ * Returns 0 for success, -1 on a legitimate error condition, and -2
+ * if the openflags used VIR_STORAGE_VOL_OPEN_NOERROR and some sort of
+ * open error occurred. It is up to the caller to handle.
+ */
 int
 virStorageBackendUpdateVolInfo(virStorageVolDefPtr vol,
                                bool withBlockVolFormat,
-- 
2.5.0