1 files changed, 114 insertions, 1 deletions

diff --git a/libssh/poll.c b/libssh/poll.c
index f2fea520..e72e6915 100644
--- a/libssh/poll.c
+++ b/libssh/poll.c
@@ -226,6 +226,19 @@ int ssh_poll(pollfd_t *fds, nfds_t nfds, int timeout) {
 
 #endif /* HAVE_POLL */
 
+/**
+ * @brief  Allocate a new poll object, which could be used within a poll context.
+ *
+ * @param  fd           Socket that will be polled.
+ * @param  events       Poll events that will be monitored for the socket. i.e.
+ *                      POLLIN, POLLPRI, POLLOUT, POLLERR, POLLHUP, POLLNVAL
+ * @param  cb           Function to be called if any of the events are set.
+ * @param  userdata     Userdata to be passed to the callback function. NULL if
+ *                      not needed.
+ *
+ * @return              A new poll object, NULL on error
+ */
+
 SSH_POLL *ssh_poll_new(socket_t fd, short events, ssh_poll_callback cb,
     void *userdata) {
   SSH_POLL *p;
@@ -242,18 +255,46 @@ SSH_POLL *ssh_poll_new(socket_t fd, short events, ssh_poll_callback cb,
   return p;
 }
 
+
+/**
+ * @brief  Free a poll object.
+ *
+ * @param  p            Pointer to an already allocated poll object.
+ */
+
 void ssh_poll_free(SSH_POLL *p) {
   SAFE_FREE(p);
 }
 
+/**
+ * @brief  Get the poll context of a poll object.
+ *
+ * @param  p            Pointer to an already allocated poll object.
+ *
+ * @return              Poll context or NULL if the poll object isn't attached.
+ */
 SSH_POLL_CTX *ssh_poll_get_ctx(SSH_POLL *p) {
   return p->ctx;
 }
 
+/**
+ * @brief  Get the events of a poll object.
+ *
+ * @param  p            Pointer to an already allocated poll object.
+ *
+ * @return              Poll events.
+ */
 short ssh_poll_get_events(SSH_POLL *p) {
   return p->events;
 }
 
+/**
+ * @brief  Set the events of a poll object. The events will also be propagated
+ *         to an associated poll context.
+ *
+ * @param  p            Pointer to an already allocated poll object.
+ * @param  events       Poll events.
+ */
 void ssh_poll_set_events(SSH_POLL *p, short events) {
   p->events = events;
   if (p->ctx != NULL) {
@@ -261,14 +302,36 @@ void ssh_poll_set_events(SSH_POLL *p, short events) {
   }
 }
 
+/**
+ * @brief  Add extra events to a poll object. Duplicates are ignored.
+ *         The events will also be propagated to an associated poll context.
+ *
+ * @param  p            Pointer to an already allocated poll object.
+ * @param  events       Poll events.
+ */
 void ssh_poll_add_events(SSH_POLL *p, short events) {
   ssh_poll_set_events(p, ssh_poll_get_events(p) | events);
 }
 
+/**
+ * @brief  Remove events from a poll object. Non-existent are ignored.
+ *         The events will also be propagated to an associated poll context.
+ *
+ * @param  p            Pointer to an already allocated poll object.
+ * @param  events       Poll events.
+ */
 void ssh_poll_remove_events(SSH_POLL *p, short events) {
   ssh_poll_set_events(p, ssh_poll_get_events(p) & ~events);
 }
 
+/**
+ * @brief  Get the raw socket of a poll object.
+ *
+ * @param  p            Pointer to an already allocated poll object.
+ *
+ * @return              Raw socket.
+ */
+
 int ssh_poll_get_fd(SSH_POLL *p) {
   if (p->ctx != NULL) {
     return p->ctx->pollfds[p->idx].fd;
@@ -276,7 +339,14 @@ int ssh_poll_get_fd(SSH_POLL *p) {
 
   return p->fd;
 }
-
+/**
+ * @brief  Set the callback of a poll object.
+ *
+ * @param  p            Pointer to an already allocated poll object.
+ * @param  cb           Function to be called if any of the events are set.
+ * @param  userdata     Userdata to be passed to the callback function. NULL if
+ *                      not needed.
+ */
 void ssh_poll_set_callback(SSH_POLL *p, ssh_poll_callback cb, void *userdata) {
   if (cb != NULL) {
     p->cb = cb;
@@ -284,6 +354,17 @@ void ssh_poll_set_callback(SSH_POLL *p, ssh_poll_callback cb, void *userdata) {
   }
 }
 
+/**
+ * @brief  Create a new poll context. It could be associated with many poll object
+ *         which are going to be polled at the same time as the poll context. You
+ *         would need a single poll context per thread.
+ *
+ * @param  chunk_size   The size of the memory chunk that will be allocated, when
+ *                      more memory is needed. This is for efficiency reasons,
+ *                      i.e. don't allocate memory for each new poll object, but
+ *                      for the next 5. Set it to 0 if you want to use the
+ *                      library's default value.
+ */
 SSH_POLL_CTX *ssh_poll_ctx_new(size_t chunk_size) {
   SSH_POLL_CTX *ctx;
 
@@ -303,6 +384,11 @@ SSH_POLL_CTX *ssh_poll_ctx_new(size_t chunk_size) {
   return ctx;
 }
 
+/**
+ * @brief  Free a poll context.
+ *
+ * @param  ctx          Pointer to an already allocated poll context.
+ */
 void ssh_poll_ctx_free(SSH_POLL_CTX *ctx) {
   if (ctx->polls_allocated > 0) {
     register size_t i, used;
@@ -349,6 +435,14 @@ static int ssh_poll_ctx_resize(SSH_POLL_CTX *ctx, size_t new_size) {
   return 0;
 }
 
+/**
+ * @brief  Add a poll object to a poll context.
+ *
+ * @param  ctx          Pointer to an already allocated poll context.
+ * @param  p            Pointer to an already allocated poll object.
+ *
+ * @return              0 on success, < 0 on error
+ */
 int ssh_poll_ctx_add(SSH_POLL_CTX *ctx, SSH_POLL *p) {
   int fd;
 
@@ -373,6 +467,12 @@ int ssh_poll_ctx_add(SSH_POLL_CTX *ctx, SSH_POLL *p) {
   return 0;
 }
 
+/**
+ * @brief  Remove a poll object from a poll context.
+ *
+ * @param  ctx          Pointer to an already allocated poll context.
+ * @param  p            Pointer to an already allocated poll object.
+ */
 void ssh_poll_ctx_remove(SSH_POLL_CTX *ctx, SSH_POLL *p) {
   size_t i;
 
@@ -394,6 +494,19 @@ void ssh_poll_ctx_remove(SSH_POLL_CTX *ctx, SSH_POLL *p) {
   }
 }
 
+/**
+ * @brief  Poll all the sockets associated through a poll object with a
+ *         poll context. If any of the events are set after the poll, the
+ *         call back function of the socket will be called.
+ *         This function should be called once within the programs main loop.
+ *
+ * @param  ctx          Pointer to an already allocated poll context.
+ * @param  timeout      An upper limit on the time for which ssh_poll_ctx() will
+ *                      block, in milliseconds. Specifying a negative value
+ *                      means an infinite timeout. This parameter is passed to
+ *                      the poll() function.
+ */
+
 int ssh_poll_ctx(SSH_POLL_CTX *ctx, int timeout) {
   int rc;