[sheepdog] [PATCH 2/3] shared lib: add the function description

[Liu Yuan]

From: Liu Yuan <liuyuan at cmss.chinamobile.com>

Signed-off-by: Liu Yuan <liuyuan at cmss.chinamobile.com>
---
 lib/shared/sheepdog.h | 70 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 68 insertions(+), 2 deletions(-)

diff --git a/lib/shared/sheepdog.h b/lib/shared/sheepdog.h
index f0be852..daa16e7 100644
--- a/lib/shared/sheepdog.h
+++ b/lib/shared/sheepdog.h
@@ -63,12 +63,78 @@ struct sd_vdi {
 	char *name;
 };
 
+/*
+ * Connect to the specified Sheepdog cluster.
+ *
+ * @host: string in the form of IP:PORT that identify a valid Sheepdog cluster.
+ *
+ * Return a cluster descriptor on success. Otherwise, return NULL in case of
+ * error and set errno as error code defined in sheepdog_proto.h.
+ */
 struct sd_cluster *sd_connect(char *host);
-int sd_disconnect(struct sd_cluster *sd);
+
+/*
+ * Disconnect to the specified sheepdog cluster.
+ *
+ * @c: pointer to the structure that returned by sd_connect().
+ *
+ * Return error code defined in sheepdog_proto.h.
+ */
+int sd_disconnect(struct sd_cluster *c);
+
+/*
+ * Run the Sheepdog request on the specified cluster synchronously.
+ *
+ * @c: pointer to the structure that returned by sd_connect().
+ * @hdr: pointer to the sheepdog request header descriptor.
+ * @data: pointer to the data for hdr.
+ *
+ * Return error code defined in sheepdog_proto.h.
+ */
 int sd_run_sdreq(struct sd_cluster *c, struct sd_req *hdr, void *data);
-struct sd_vdi *sd_vdi_open(struct sd_cluster *sd, char *name);
+
+/*
+ * Open the named vdi from the specified cluster.
+ *
+ * @c: pointer to the structure that returned by sd_connect().
+ * @name: the name of the vdi to be opened.
+ *
+ * Return a vdi descriptor on success. Otherwise, return NULL in case of
+ * error and set errno as error code defined in sheepdog_proto.h.
+ */
+struct sd_vdi *sd_vdi_open(struct sd_cluster *c, char *name);
+
+/*
+ * Read from a vdi descriptor at a given offset.
+ *
+ * @vdi: pointer to the structure that returned by sd_vdi_open().
+ * @buf: the buffer to hold the data.
+ * @count: how many bytes we read up to.
+ * @offset: the start of the vdi we try to read.
+ *
+ * Return error code defined in sheepdog_proto.h.
+ */
 int sd_vdi_read(struct sd_vdi *vdi, void *buf, size_t count, off_t offset);
+
+/*
+ * Write to a vdi descriptor at a given offset.
+ *
+ * @vdi: pointer to the structure that returned by sd_vdi_open().
+ * @buf: the buffer to hold the data.
+ * @count: how many bytes we write up to.
+ * @offset: the start of the vdi we try to write.
+ *
+ * Return error code defined in sheepdog_proto.h.
+ */
 int sd_vdi_write(struct sd_vdi *vdi, void *buf, size_t count, off_t offset);
+
+/*
+ * Close a vdi descriptor.
+ *
+ * @vdi: pointer to the structure that returned by sd_vdi_open().
+ *
+ * Return error code defined in sheepdog_proto.h.
+ */
 int sd_vdi_close(struct sd_vdi *vdi);
 
 #endif
-- 
1.9.1