More comments for connection.c/h and wayland-util.hHEADmaster

3 files changed, 70 insertions, 1 deletions

diff --git a/connection.c b/connection.c
index d969531..ca58dc9 100644
--- a/connection.c
+++ b/connection.c
@@ -77,6 +77,14 @@ wl_connection_destroy(struct wl_connection *connection)
 	free(connection);
 }
 
+/**
+ * Copy data out of the in buffer for `connection`. Note data is NOT removed
+ * from the buffer. Also note there's no checking done for underruns (FIXME?)
+ *
+ * connection: Connection to get data from.
+ * data: Where to copy the data.
+ * size: How much data to copy.
+ **/
 void
 wl_connection_copy(struct wl_connection *connection, void *data, size_t size)
 {
@@ -94,6 +102,12 @@ wl_connection_copy(struct wl_connection *connection, void *data, size_t size)
 	}
 }
 
+/**
+ * Discard `size` bytes from the in buffer of `connection`.
+ *
+ * connection: Connection to operate on.
+ * size: Bytes to discard.
+ **/
 void
 wl_connection_consume(struct wl_connection *connection, size_t size)
 {
@@ -110,6 +124,16 @@ wl_connection_consume(struct wl_connection *connection, size_t size)
 	}
 }
 
+/**
+ * Attempt to read and write `connection` until the in and out buffers are
+ * empty and full respectively. Returns the amount of data available in the in
+ * buffer, or 0 if the in buffer is not updated due to the `mask` argument.
+ *
+ * connection: Connection to operate on.
+ * mask: ORing of WL_CONNECTION_READABLE and WL_CONNECTION writeable to
+ * 	determine whether the read and write buffers respectively should be
+ * 	operated on.
+ **/
 int wl_connection_data(struct wl_connection *connection, uint32_t mask)
 {
 	struct wl_buffer *b;
@@ -200,6 +224,13 @@ int wl_connection_data(struct wl_connection *connection, uint32_t mask)
 	return available;
 }
 
+/**
+ * Copy data into the write buffer for `connection`.
+ *
+ * connection: Connection to write to.
+ * data: Data to copy.
+ * count: Size of `data`.
+ **/
 void
 wl_connection_write(struct wl_connection *connection, const void *data, size_t count)
 {
@@ -226,6 +257,18 @@ wl_connection_write(struct wl_connection *connection, const void *data, size_t c
 				   connection->data);
 }
 
+/**
+ * Send a message from an object to the other end of the connection. If the
+ * message is a method call then the object will tend to be a proxy. If it is
+ * an event the object will likely be a regular object. At the moment at most
+ * 30 arguments can be processed.
+ *
+ * connection: The connection to send on.
+ * sender: The object to originate from.
+ * opcode: Index of the message type within the interface for `sender`.
+ * ap: A va_list which can be used to glean arguments for the method.
+ * message: The message being sent.
+ **/
 void
 wl_connection_vmarshal(struct wl_connection *connection,
 		       struct wl_object *sender,
@@ -282,6 +325,18 @@ wl_connection_vmarshal(struct wl_connection *connection,
 	wl_connection_write(connection, args, size);
 }
 
+/**
+ * Read a message from a connection and pass its arguments to a function.
+ * 
+ * connection: Connection to read from.
+ * size: Amount to read.
+ * objects: Hash table of objects so if the message contains object IDs they
+ * 	may be resolved.
+ * func: Function to call.
+ * data: Misc. data passed as first arg to `func`.
+ * target: Object this message is addressed to.
+ * message: wl_message specifying this message's signature.
+ **/
 void
 wl_connection_demarshal(struct wl_connection *connection,
 			uint32_t size,
@@ -312,6 +367,7 @@ wl_connection_demarshal(struct wl_connection *connection,
 	}
 
 	if (sizeof buffer < size) {
+		/* FIXME */
 		printf("request too big, should malloc tmp buffer here\n");
 		return;
 	}
diff --git a/connection.h b/connection.h
index 30e82e1..bc66a56 100644
--- a/connection.h
+++ b/connection.h
@@ -28,6 +28,10 @@
 
 struct wl_connection;
 
+/**
+ * Flags indicate whether a connection is ready to be written to or has data to
+ * be read.
+ **/
 #define WL_CONNECTION_READABLE 0x01
 #define WL_CONNECTION_WRITABLE 0x02
 
diff --git a/wayland-util.h b/wayland-util.h
index 18891ec..09ad6bc 100644
--- a/wayland-util.h
+++ b/wayland-util.h
@@ -79,8 +79,17 @@ struct wl_argument {
 /**
  * A name and signature for a method or event in a wl_interface.
  *
+ * The signature is a string with each character representing one argument and
+ * denoting type:
+ * 	u: Unsigned 32-bit int.
+ * 	i: Signed 32-bit int.
+ * 	s: String.
+ * 	o: Object (by ID).
+ * 	n: New object. (TODO: Clarify this. Its not quite right.)
+ * 	a: Array.
+ *
  * name: Name of this message.
- * signature: What arguments this message comes with, in DBus style.
+ * signature: What arguments this message comes with.
  * types: FIXME: This appears to be unused.
  **/
 struct wl_message {