Complete documentation of public interface and fix a lot of bogus comments

This change unifies the documentation comment syntax, fixes a few bad
documentation comments and completes documentation where it was missing.

10 files changed, 416 insertions, 232 deletions

diff --git a/src/afc.c b/src/afc.c
index e966fa5..5def00c 100644
--- a/src/afc.c
+++ b/src/afc.c
@@ -27,10 +27,11 @@
 #include "idevice.h"
 #include "debug.h"
 
-// This is the maximum size an AFC data packet can be
+/** The maximum size an AFC data packet can be */
 static const int MAXIMUM_PACKET_SIZE = (2 << 15);
 
-/** Locks an AFC client, done for thread safety stuff
+/**
+ * Locks an AFC client, done for thread safety stuff
  * 
  * @param client The AFC client connection to lock
  */
@@ -40,7 +41,8 @@ static void afc_lock(afc_client_t client)
         g_mutex_lock(client->mutex);
 }
 
-/** Unlocks an AFC client, done for thread safety stuff.
+/**
+ * Unlocks an AFC client, done for thread safety stuff.
  * 
  * @param client The AFC 
  */
@@ -50,7 +52,8 @@ static void afc_unlock(afc_client_t client)
         g_mutex_unlock(client->mutex);
 }
 
-/** Makes a connection to the AFC service on the phone. 
+/**
+ * Makes a connection to the AFC service on the phone.
  * 
  * @param device The device to connect to.
  * @param port The destination port.
@@ -118,14 +121,15 @@ afc_error_t afc_client_free(afc_client_t client)
         return AFC_E_SUCCESS;
 }
 
-/** Dispatches an AFC packet over a client.
+/**
+ * Dispatches an AFC packet over a client.
  * 
  * @param client The client to send data through.
  * @param data The data to send.
  * @param length The length to send.
  * @param bytes_sent The number of bytes actually sent.
  *
- * @return AFC_E_SUCCESS on success, or an AFC_E_* error value on error.
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
  * 
  * @warning set client->afc_packet->this_length and
  *          client->afc_packet->entire_length to 0 before calling this.  The
@@ -153,9 +157,9 @@ static afc_error_t afc_dispatch_packet(afc_client_t client, const char *data, ui
         if (!client->afc_packet->this_length) {
                 client->afc_packet->this_length = sizeof(AFCPacket);
         }
-        // We want to send two segments; buffer+sizeof(AFCPacket) to
-        // this_length is the parameters
-        // And everything beyond that is the next packet. (for writing)
+        /* We want to send two segments; buffer+sizeof(AFCPacket) to this_length
+           is the parameters and everything beyond that is the next packet.
+           (for writing) */
         if (client->afc_packet->this_length != client->afc_packet->entire_length) {
                 offset = client->afc_packet->this_length - sizeof(AFCPacket);
 
@@ -222,14 +226,14 @@ static afc_error_t afc_dispatch_packet(afc_client_t client, const char *data, ui
         return AFC_E_INTERNAL_ERROR;
 }
 
-/** Receives data through an AFC client and sets a variable to the received data.
+/**
+ * Receives data through an AFC client and sets a variable to the received data.
  * 
  * @param client The client to receive data on.
  * @param dump_here The char* to point to the newly-received data.
  * @param bytes_recv How much data was received.
  * 
- * @return AFC_E_SUCCESS when data has been received, or an AFC_E_* error value
- *         when an error occured.
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
  */
 static afc_error_t afc_receive_data(afc_client_t client, char **dump_here, uint32_t *bytes_recv)
 {
@@ -371,6 +375,9 @@ static afc_error_t afc_receive_data(afc_client_t client, char **dump_here, uint3
         return AFC_E_SUCCESS;
 }
 
+/**
+ * Returns counts of null characters within a string.
+ */
 static uint32_t count_nullspaces(char *string, uint32_t number)
 {
         uint32_t i = 0, nulls = 0;
@@ -412,13 +419,15 @@ static char **make_strings_list(char *tokens, uint32_t length)
         return list;
 }
 
-/** Gets a directory listing of the directory requested.
+/**
+ * Gets a directory listing of the directory requested.
  * 
  * @param client The client to get a directory listing from.
  * @param dir The directory to list. (must be a fully-qualified path)
+ * @param list A char list of files in that directory, terminated by an empty
+ *         string or NULL if there was an error.
  * 
- * @return A char ** list of files in that directory, terminated by an empty
- *         string for now or NULL if there was an error.
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
  */
 afc_error_t afc_read_directory(afc_client_t client, const char *dir, char ***list)
 {
@@ -431,7 +440,7 @@ afc_error_t afc_read_directory(afc_client_t client, const char *dir, char ***lis
 
         afc_lock(client);
 
-        // Send the command
+        /* Send the command */
         client->afc_packet->operation = AFC_OP_READ_DIR;
         client->afc_packet->entire_length = 0;
         client->afc_packet->this_length = 0;
@@ -440,13 +449,13 @@ afc_error_t afc_read_directory(afc_client_t client, const char *dir, char ***lis
                 afc_unlock(client);
                 return AFC_E_NOT_ENOUGH_DATA;
         }
-        // Receive the data
+        /* Receive the data */
         ret = afc_receive_data(client, &data, &bytes);
         if (ret != AFC_E_SUCCESS) {
                 afc_unlock(client);
                 return ret;
         }
-        // Parse the data
+        /* Parse the data */
         list_loc = make_strings_list(data, bytes);
         if (data)
                 free(data);
@@ -457,12 +466,16 @@ afc_error_t afc_read_directory(afc_client_t client, const char *dir, char ***lis
         return ret;
 }
 
-/** Get device info for a client connection to phone. (free space on disk, etc.)
+/**
+ * Get device info for a client connection to phone. The device information
+ * returned is the device model as well as the free space, the total capacity
+ * and blocksize on the accessed disk partition.
  * 
  * @param client The client to get device info for.
+ * @param infos A char ** list of parameters as given by AFC or NULL if there
+ *  was an error.
  * 
- * @return A char ** list of parameters as given by AFC or NULL if there was an
- *         error.
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
  */
 afc_error_t afc_get_device_info(afc_client_t client, char ***infos)
 {
@@ -475,7 +488,7 @@ afc_error_t afc_get_device_info(afc_client_t client, char ***infos)
 
         afc_lock(client);
 
-        // Send the command
+        /* Send the command */
         client->afc_packet->operation = AFC_OP_GET_DEVINFO;
         client->afc_packet->entire_length = client->afc_packet->this_length = 0;
         ret = afc_dispatch_packet(client, NULL, 0, &bytes);
@@ -483,13 +496,13 @@ afc_error_t afc_get_device_info(afc_client_t client, char ***infos)
                 afc_unlock(client);
                 return AFC_E_NOT_ENOUGH_DATA;
         }
-        // Receive the data
+        /* Receive the data */
         ret = afc_receive_data(client, &data, &bytes);
         if (ret != AFC_E_SUCCESS) {
                 afc_unlock(client);
                 return ret;
         }
-        // Parse the data
+        /* Parse the data */
         list = make_strings_list(data, bytes);
         if (data)
                 free(data);
@@ -501,7 +514,8 @@ afc_error_t afc_get_device_info(afc_client_t client, char ***infos)
         return ret;
 }
 
-/** Get a specific key of the device info list for a client connection.
+/**
+ * Get a specific key of the device info list for a client connection.
  * Known key values are: Model, FSTotalBytes, FSFreeBytes and FSBlockSize.
  * This is a helper function for afc_get_device_info().
  *
@@ -536,7 +550,8 @@ afc_error_t afc_get_device_info_key(afc_client_t client, const char *key, char *
         return ret;
 }
 
-/** Deletes a file or directory.
+/**
+ * Deletes a file or directory.
  * 
  * @param client The client to use.
  * @param path The path to delete. (must be a fully-qualified path)
@@ -554,7 +569,7 @@ afc_error_t afc_remove_path(afc_client_t client, const char *path)
 
         afc_lock(client);
 
-        // Send command
+        /* Send command */
         client->afc_packet->this_length = client->afc_packet->entire_length = 0;
         client->afc_packet->operation = AFC_OP_REMOVE_PATH;
         ret = afc_dispatch_packet(client, path, strlen(path)+1, &bytes);
@@ -562,7 +577,7 @@ afc_error_t afc_remove_path(afc_client_t client, const char *path)
                 afc_unlock(client);
                 return AFC_E_NOT_ENOUGH_DATA;
         }
-        // Receive response
+        /* Receive response */
         ret = afc_receive_data(client, &response, &bytes);
         if (response)
                 free(response);
@@ -576,7 +591,8 @@ afc_error_t afc_remove_path(afc_client_t client, const char *path)
         return ret;
 }
 
-/** Renames a file or directory on the phone.
+/**
+ * Renames a file or directory on the phone.
  * 
  * @param client The client to have rename.
  * @param from The name to rename from. (must be a fully-qualified path)
@@ -596,7 +612,7 @@ afc_error_t afc_rename_path(afc_client_t client, const char *from, const char *t
 
         afc_lock(client);
 
-        // Send command
+        /* Send command */
         memcpy(send, from, strlen(from) + 1);
         memcpy(send + strlen(from) + 1, to, strlen(to) + 1);
         client->afc_packet->entire_length = client->afc_packet->this_length = 0;
@@ -607,7 +623,7 @@ afc_error_t afc_rename_path(afc_client_t client, const char *from, const char *t
                 afc_unlock(client);
                 return AFC_E_NOT_ENOUGH_DATA;
         }
-        // Receive response
+        /* Receive response */
         ret = afc_receive_data(client, &response, &bytes);
         if (response)
                 free(response);
@@ -617,7 +633,8 @@ afc_error_t afc_rename_path(afc_client_t client, const char *from, const char *t
         return ret;
 }
 
-/** Creates a directory on the phone.
+/**
+ * Creates a directory on the phone.
  * 
  * @param client The client to use to make a directory.
  * @param dir The directory's path. (must be a fully-qualified path, I assume
@@ -636,7 +653,7 @@ afc_error_t afc_make_directory(afc_client_t client, const char *dir)
 
         afc_lock(client);
 
-        // Send command
+        /* Send command */
         client->afc_packet->operation = AFC_OP_MAKE_DIR;
         client->afc_packet->this_length = client->afc_packet->entire_length = 0;
         ret = afc_dispatch_packet(client, dir, strlen(dir)+1, &bytes);
@@ -644,7 +661,7 @@ afc_error_t afc_make_directory(afc_client_t client, const char *dir)
                 afc_unlock(client);
                 return AFC_E_NOT_ENOUGH_DATA;
         }
-        // Receive response
+        /* Receive response */
         ret = afc_receive_data(client, &response, &bytes);
         if (response)
                 free(response);
@@ -654,7 +671,8 @@ afc_error_t afc_make_directory(afc_client_t client, const char *dir)
         return ret;
 }
 
-/** Gets information about a specific file.
+/**
+ * Gets information about a specific file.
  * 
  * @param client The client to use to get the information of the file.
  * @param path The fully-qualified path to the file. 
@@ -662,8 +680,7 @@ afc_error_t afc_make_directory(afc_client_t client, const char *dir)
  *                 list of strings with the file information.
  *                 Set to NULL before calling this function.
  * 
- * @return AFC_E_SUCCESS on success or an AFC_E_* error value
- *         when something went wrong.
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
  */
 afc_error_t afc_get_file_info(afc_client_t client, const char *path, char ***infolist)
 {
@@ -676,7 +693,7 @@ afc_error_t afc_get_file_info(afc_client_t client, const char *path, char ***inf
 
         afc_lock(client);
 
-        // Send command
+        /* Send command */
         client->afc_packet->operation = AFC_OP_GET_FILE_INFO;
         client->afc_packet->entire_length = client->afc_packet->this_length = 0;
         ret = afc_dispatch_packet(client, path, strlen(path)+1, &bytes);
@@ -685,7 +702,7 @@ afc_error_t afc_get_file_info(afc_client_t client, const char *path, char ***inf
                 return AFC_E_NOT_ENOUGH_DATA;
         }
 
-        // Receive data
+        /* Receive data */
         ret = afc_receive_data(client, &received, &bytes);
         if (received) {
                 *infolist = make_strings_list(received, bytes);
@@ -697,7 +714,8 @@ afc_error_t afc_get_file_info(afc_client_t client, const char *path, char ***inf
         return ret;
 }
 
-/** Opens a file on the phone.
+/**
+ * Opens a file on the phone.
  * 
  * @param client The client to use to open the file. 
  * @param filename The file to open. (must be a fully-qualified path)
@@ -707,7 +725,7 @@ afc_error_t afc_get_file_info(afc_client_t client, const char *path, char ***inf
  *                  destroying anything previously there.
  * @param handle Pointer to a uint64_t that will hold the handle of the file
  * 
- * @return AFC_E_SUCCESS on success or an AFC_E_* error on failure.
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
  */
 idevice_error_t
 afc_file_open(afc_client_t client, const char *filename,
@@ -718,7 +736,7 @@ afc_file_open(afc_client_t client, const char *filename,
         char *data = (char *) malloc(sizeof(char) * (8 + strlen(filename) + 1));
         afc_error_t ret = AFC_E_UNKNOWN_ERROR;
 
-        // set handle to 0 so in case an error occurs, the handle is invalid
+        /* set handle to 0 so in case an error occurs, the handle is invalid */
         *handle = 0;
 
         if (!client || !client->connection || !client->afc_packet)
@@ -726,7 +744,7 @@ afc_file_open(afc_client_t client, const char *filename,
 
         afc_lock(client);
 
-        // Send command
+        /* Send command */
         memcpy(data, &file_mode_loc, 8);
         memcpy(data + 8, filename, strlen(filename));
         data[8 + strlen(filename)] = '\0';
@@ -740,12 +758,12 @@ afc_file_open(afc_client_t client, const char *filename,
                 afc_unlock(client);
                 return AFC_E_NOT_ENOUGH_DATA;
         }
-        // Receive the data
+        /* Receive the data */
         ret = afc_receive_data(client, &data, &bytes);
         if ((ret == AFC_E_SUCCESS) && (bytes > 0) && data) {
                 afc_unlock(client);
 
-                // Get the file handle
+                /* Get the file handle */
                 memcpy(handle, data, sizeof(uint64_t));
                 free(data);
                 return ret;
@@ -758,7 +776,8 @@ afc_file_open(afc_client_t client, const char *filename,
         return ret;
 }
 
-/** Attempts to the read the given number of bytes from the given file.
+/**
+ * Attempts to the read the given number of bytes from the given file.
  * 
  * @param client The relevant AFC client
  * @param handle File handle of a previously opened file
@@ -766,7 +785,7 @@ afc_file_open(afc_client_t client, const char *filename,
  * @param length The number of bytes to read
  * @param bytes_read The number of bytes actually read.
  *
- * @return AFC_E_SUCCESS on success or an AFC_E_* error value on error.
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
  */
 idevice_error_t
 afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length, uint32_t *bytes_read)
@@ -782,12 +801,12 @@ afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length,
 
         afc_lock(client);
 
-        // Looping here to get around the maximum amount of data that
-        // afc_receive_data can handle
+        /* Looping here to get around the maximum amount of data that
+           afc_receive_data can handle */
         while (current_count < length) {
                 debug_info("current count is %i but length is %i", current_count, length);
 
-                // Send the read command
+                /* Send the read command */
                 AFCFilePacket *packet = (AFCFilePacket *) malloc(sizeof(AFCFilePacket));
                 packet->filehandle = handle;
                 packet->size = GUINT64_TO_LE(((length - current_count) < MAXIMUM_READ_SIZE) ? (length - current_count) : MAXIMUM_READ_SIZE);
@@ -800,7 +819,7 @@ afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length,
                         afc_unlock(client);
                         return AFC_E_NOT_ENOUGH_DATA;
                 }
-                // Receive the data
+                /* Receive the data */
                 ret = afc_receive_data(client, &input, &bytes_loc);
                 debug_info("afc_receive_data returned error: %d", ret);
                 debug_info("bytes returned: %i", bytes_loc);
@@ -831,7 +850,8 @@ afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length,
         return ret;
 }
 
-/** Writes a given number of bytes to a file.
+/**
+ * Writes a given number of bytes to a file.
  * 
  * @param client The client to use to write to the file.
  * @param handle File handle of previously opened file. 
@@ -839,7 +859,7 @@ afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length,
  * @param length How much data to write.
  * @param bytes_written The number of bytes actually written to the file.
  * 
- * @return AFC_E_SUCCESS on success, or an AFC_E_* error value on error.
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
  */
 idevice_error_t
 afc_file_write(afc_client_t client, uint64_t handle, const char *data, uint32_t length, uint32_t *bytes_written)
@@ -859,9 +879,9 @@ afc_file_write(afc_client_t client, uint64_t handle, const char *data, uint32_t
 
         debug_info("Write length: %i", length);
 
-        // Divide the file into segments.
+        /* Divide the file into segments. */
         for (i = 0; i < segments; i++) {
-                // Send the segment
+                /* Send the segment */
                 client->afc_packet->this_length = sizeof(AFCPacket) + 8;
                 client->afc_packet->entire_length = client->afc_packet->this_length + MAXIMUM_WRITE_SIZE;
                 client->afc_packet->operation = AFC_OP_WRITE;
@@ -886,10 +906,9 @@ afc_file_write(afc_client_t client, uint64_t handle, const char *data, uint32_t
                 }
         }
 
-        // By this point, we should be at the end. i.e. the last segment that
-        // didn't get sent in the for loop
-        // this length is fine because it's always sizeof(AFCPacket) + 8, but
-        // to be sure we do it again
+        /* By this point, we should be at the end. i.e. the last segment that didn't
+           get sent in the for loop. This length is fine because it's always
+           sizeof(AFCPacket) + 8, but to be sure we do it again */
         if (current_count == length) {
                 afc_unlock(client);
                 *bytes_written = current_count;
@@ -925,7 +944,8 @@ afc_file_write(afc_client_t client, uint64_t handle, const char *data, uint32_t
         return ret;
 }
 
-/** Closes a file on the phone. 
+/**
+ * Closes a file on the phone.
  * 
  * @param client The client to close the file with.
  * @param handle File handle of a previously opened file.
@@ -943,7 +963,7 @@ afc_error_t afc_file_close(afc_client_t client, uint64_t handle)
 
         debug_info("File handle %i", handle);
 
-        // Send command
+        /* Send command */
         memcpy(buffer, &handle, sizeof(uint64_t));
         client->afc_packet->operation = AFC_OP_FILE_CLOSE;
         client->afc_packet->entire_length = client->afc_packet->this_length = 0;
@@ -956,7 +976,7 @@ afc_error_t afc_file_close(afc_client_t client, uint64_t handle)
                 return AFC_E_UNKNOWN_ERROR;
         }
 
-        // Receive the response
+        /* Receive the response */
         ret = afc_receive_data(client, &buffer, &bytes);
         if (buffer)
                 free(buffer);
@@ -966,7 +986,8 @@ afc_error_t afc_file_close(afc_client_t client, uint64_t handle)
         return ret;
 }
 
-/** Locks or unlocks a file on the phone. 
+/**
+ * Locks or unlocks a file on the phone. 
  *
  * makes use of flock on the device, see
  * http://developer.apple.com/documentation/Darwin/Reference/ManPages/man2/flock.2.html
@@ -991,7 +1012,7 @@ afc_error_t afc_file_lock(afc_client_t client, uint64_t handle, afc_lock_op_t op
 
         debug_info("file handle %i", handle);
 
-        // Send command
+        /* Send command */
         memcpy(buffer, &handle, sizeof(uint64_t));
         memcpy(buffer + 8, &op, 8);
 
@@ -1006,7 +1027,7 @@ afc_error_t afc_file_lock(afc_client_t client, uint64_t handle, afc_lock_op_t op
                 debug_info("could not send lock command");
                 return AFC_E_UNKNOWN_ERROR;
         }
-        // Receive the response
+        /* Receive the response */
         ret = afc_receive_data(client, &buffer, &bytes);
         if (buffer) {
                 debug_buffer(buffer, bytes);
@@ -1017,14 +1038,15 @@ afc_error_t afc_file_lock(afc_client_t client, uint64_t handle, afc_lock_op_t op
         return ret;
 }
 
-/** Seeks to a given position of a pre-opened file on the phone. 
+/**
+ * Seeks to a given position of a pre-opened file on the phone. 
  * 
  * @param client The client to use to seek to the position.
  * @param handle File handle of a previously opened.
  * @param offset Seek offset.
  * @param whence Seeking direction, one of SEEK_SET, SEEK_CUR, or SEEK_END.
  * 
- * @return AFC_E_SUCCESS on success, AFC_E_NOT_ENOUGH_DATA on failure.
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
  */
 afc_error_t afc_file_seek(afc_client_t client, uint64_t handle, int64_t offset, int whence)
 {
@@ -1039,10 +1061,10 @@ afc_error_t afc_file_seek(afc_client_t client, uint64_t handle, int64_t offset,
 
         afc_lock(client);
 
-        // Send the command
-        memcpy(buffer, &handle, sizeof(uint64_t));      // handle
-        memcpy(buffer + 8, &whence_loc, sizeof(uint64_t));      // fromwhere
-        memcpy(buffer + 16, &offset_loc, sizeof(uint64_t));     // offset
+        /* Send the command */
+        memcpy(buffer, &handle, sizeof(uint64_t));      /* handle */
+        memcpy(buffer + 8, &whence_loc, sizeof(uint64_t));      /* fromwhere */
+        memcpy(buffer + 16, &offset_loc, sizeof(uint64_t));     /* offset */
         client->afc_packet->operation = AFC_OP_FILE_SEEK;
         client->afc_packet->this_length = client->afc_packet->entire_length = 0;
         ret = afc_dispatch_packet(client, buffer, 24, &bytes);
@@ -1053,7 +1075,7 @@ afc_error_t afc_file_seek(afc_client_t client, uint64_t handle, int64_t offset,
                 afc_unlock(client);
                 return AFC_E_NOT_ENOUGH_DATA;
         }
-        // Receive response
+        /* Receive response */
         ret = afc_receive_data(client, &buffer, &bytes);
         if (buffer)
                 free(buffer);
@@ -1063,13 +1085,14 @@ afc_error_t afc_file_seek(afc_client_t client, uint64_t handle, int64_t offset,
         return ret;
 }
 
-/** Returns current position in a pre-opened file on the phone.
+/**
+ * Returns current position in a pre-opened file on the phone.
  * 
  * @param client The client to use.
  * @param handle File handle of a previously opened file.
  * @param position Position in bytes of indicator
  * 
- * @return AFC_E_SUCCESS on success, AFC_E_NOT_ENOUGH_DATA on failure.
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
  */
 afc_error_t afc_file_tell(afc_client_t client, uint64_t handle, uint64_t *position)
 {
@@ -1082,8 +1105,8 @@ afc_error_t afc_file_tell(afc_client_t client, uint64_t handle, uint64_t *positi
 
         afc_lock(client);
 
-        // Send the command
-        memcpy(buffer, &handle, sizeof(uint64_t));      // handle
+        /* Send the command */
+        memcpy(buffer, &handle, sizeof(uint64_t));      /* handle */
         client->afc_packet->operation = AFC_OP_FILE_TELL;
         client->afc_packet->this_length = client->afc_packet->entire_length = 0;
         ret = afc_dispatch_packet(client, buffer, 8, &bytes);
@@ -1095,7 +1118,7 @@ afc_error_t afc_file_tell(afc_client_t client, uint64_t handle, uint64_t *positi
                 return AFC_E_NOT_ENOUGH_DATA;
         }
 
-        // Receive the data
+        /* Receive the data */
         ret = afc_receive_data(client, &buffer, &bytes);
         if (bytes > 0 && buffer) {
                 /* Get the position */
@@ -1110,13 +1133,14 @@ afc_error_t afc_file_tell(afc_client_t client, uint64_t handle, uint64_t *positi
         return ret;
 }
 
-/** Sets the size of a file on the phone.
+/**
+ * Sets the size of a file on the phone.
  * 
  * @param client The client to use to set the file size.
  * @param handle File handle of a previously opened file.
  * @param newsize The size to set the file to. 
  * 
- * @return 0 on success, -1 on failure. 
+ * @return AFC_E_SUCCESS on success or an AFC_E_* error value.
  * 
  * @note This function is more akin to ftruncate than truncate, and truncate
  *       calls would have to open the file before calling this, sadly.
@@ -1133,9 +1157,9 @@ afc_error_t afc_file_truncate(afc_client_t client, uint64_t handle, uint64_t new
 
         afc_lock(client);
 
-        // Send command
-        memcpy(buffer, &handle, sizeof(uint64_t));      // handle
-        memcpy(buffer + 8, &newsize_loc, sizeof(uint64_t));     // newsize
+        /* Send command */
+        memcpy(buffer, &handle, sizeof(uint64_t));      /* handle */
+        memcpy(buffer + 8, &newsize_loc, sizeof(uint64_t));     /* newsize */
         client->afc_packet->operation = AFC_OP_FILE_SET_SIZE;
         client->afc_packet->this_length = client->afc_packet->entire_length = 0;
         ret = afc_dispatch_packet(client, buffer, 16, &bytes);
@@ -1146,7 +1170,7 @@ afc_error_t afc_file_truncate(afc_client_t client, uint64_t handle, uint64_t new
                 afc_unlock(client);
                 return AFC_E_NOT_ENOUGH_DATA;
         }
-        // Receive response
+        /* Receive response */
         ret = afc_receive_data(client, &buffer, &bytes);
         if (buffer)
                 free(buffer);
@@ -1156,7 +1180,8 @@ afc_error_t afc_file_truncate(afc_client_t client, uint64_t handle, uint64_t new
         return ret;
 }
 
-/** Sets the size of a file on the phone without prior opening it.
+/**
+ * Sets the size of a file on the phone without prior opening it.
  * 
  * @param client The client to use to set the file size.
  * @param path The path of the file to be truncated.
@@ -1177,7 +1202,7 @@ afc_error_t afc_truncate(afc_client_t client, const char *path, uint64_t newsize
 
         afc_lock(client);
 
-        // Send command
+        /* Send command */
         memcpy(send, &size_requested, 8);
         memcpy(send + 8, path, strlen(path) + 1);
         client->afc_packet->entire_length = client->afc_packet->this_length = 0;
@@ -1188,7 +1213,7 @@ afc_error_t afc_truncate(afc_client_t client, const char *path, uint64_t newsize
                 afc_unlock(client);
                 return AFC_E_NOT_ENOUGH_DATA;
         }
-        // Receive response
+        /* Receive response */
         ret = afc_receive_data(client, &response, &bytes);
         if (response)
                 free(response);
@@ -1198,10 +1223,11 @@ afc_error_t afc_truncate(afc_client_t client, const char *path, uint64_t newsize
         return ret;
 }
 
-/** Creates a hard link or symbolic link on the device. 
+/**
+ * Creates a hard link or symbolic link on the device. 
  * 
  * @param client The client to use for making a link
- * @param type 1 = hard link, 2 = symlink
+ * @param linktype 1 = hard link, 2 = symlink
  * @param target The file to be linked.
  * @param linkname The name of link.
  * 
@@ -1224,7 +1250,7 @@ afc_error_t afc_make_link(afc_client_t client, afc_link_type_t linktype, const c
         debug_info("target: %s, length:%d", target, strlen(target));
         debug_info("linkname: %s, length:%d", linkname, strlen(linkname));
 
-        // Send command
+        /* Send command */
         memcpy(send, &type, 8);
         memcpy(send + 8, target, strlen(target) + 1);
         memcpy(send + 8 + strlen(target) + 1, linkname, strlen(linkname) + 1);
@@ -1236,7 +1262,7 @@ afc_error_t afc_make_link(afc_client_t client, afc_link_type_t linktype, const c
                 afc_unlock(client);
                 return AFC_E_NOT_ENOUGH_DATA;
         }
-        // Receive response
+        /* Receive response */
         ret = afc_receive_data(client, &response, &bytes);
         if (response)
                 free(response);
@@ -1246,7 +1272,8 @@ afc_error_t afc_make_link(afc_client_t client, afc_link_type_t linktype, const c
         return ret;
 }
 
-/** Sets the modification time of a file on the phone.
+/**
+ * Sets the modification time of a file on the phone.
  * 
  * @param client The client to use to set the file size.
  * @param path Path of the file for which the modification time should be set.
@@ -1267,7 +1294,7 @@ afc_error_t afc_set_file_time(afc_client_t client, const char *path, uint64_t mt
 
         afc_lock(client);
 
-        // Send command
+        /* Send command */
         memcpy(send, &mtime_loc, 8);
         memcpy(send + 8, path, strlen(path) + 1);
         client->afc_packet->entire_length = client->afc_packet->this_length = 0;
@@ -1278,7 +1305,7 @@ afc_error_t afc_set_file_time(afc_client_t client, const char *path, uint64_t mt
                 afc_unlock(client);
                 return AFC_E_NOT_ENOUGH_DATA;
         }
-        // Receive response
+        /* Receive response */
         ret = afc_receive_data(client, &response, &bytes);
         if (response)
                 free(response);
diff --git a/src/afc.h b/src/afc.h
index abf38e3..cde85b4 100644
--- a/src/afc.h
+++ b/src/afc.h
@@ -62,34 +62,34 @@ struct afc_client_private {
 
 /* AFC Operations */
 enum {
-        AFC_OP_STATUS          = 0x00000001,    // Status
-        AFC_OP_DATA            = 0x00000002,    // Data
-        AFC_OP_READ_DIR        = 0x00000003,    // ReadDir
-        AFC_OP_READ_FILE       = 0x00000004,    // ReadFile
-        AFC_OP_WRITE_FILE      = 0x00000005,    // WriteFile
-        AFC_OP_WRITE_PART      = 0x00000006,    // WritePart
-        AFC_OP_TRUNCATE        = 0x00000007,    // TruncateFile
-        AFC_OP_REMOVE_PATH     = 0x00000008,    // RemovePath
-        AFC_OP_MAKE_DIR        = 0x00000009,    // MakeDir
-        AFC_OP_GET_FILE_INFO   = 0x0000000a,    // GetFileInfo
-        AFC_OP_GET_DEVINFO     = 0x0000000b,    // GetDeviceInfo
-        AFC_OP_WRITE_FILE_ATOM = 0x0000000c,    // WriteFileAtomic (tmp file+rename)
-        AFC_OP_FILE_OPEN       = 0x0000000d,    // FileRefOpen
-        AFC_OP_FILE_OPEN_RES   = 0x0000000e,    // FileRefOpenResult
-        AFC_OP_READ            = 0x0000000f,    // FileRefRead
-        AFC_OP_WRITE           = 0x00000010,    // FileRefWrite
-        AFC_OP_FILE_SEEK       = 0x00000011,    // FileRefSeek
-        AFC_OP_FILE_TELL       = 0x00000012,    // FileRefTell
-        AFC_OP_FILE_TELL_RES   = 0x00000013,    // FileRefTellResult
-        AFC_OP_FILE_CLOSE      = 0x00000014,    // FileRefClose
-        AFC_OP_FILE_SET_SIZE   = 0x00000015,    // FileRefSetFileSize (ftruncate)
-        AFC_OP_GET_CON_INFO    = 0x00000016,    // GetConnectionInfo
-        AFC_OP_SET_CON_OPTIONS = 0x00000017,    // SetConnectionOptions
-        AFC_OP_RENAME_PATH     = 0x00000018,    // RenamePath
-        AFC_OP_SET_FS_BS       = 0x00000019,    // SetFSBlockSize (0x800000)
-        AFC_OP_SET_SOCKET_BS   = 0x0000001A,    // SetSocketBlockSize (0x800000)
-        AFC_OP_FILE_LOCK       = 0x0000001B,    // FileRefLock
-        AFC_OP_MAKE_LINK       = 0x0000001C,    // MakeLink
-        AFC_OP_SET_FILE_TIME   = 0x0000001E     // set st_mtime
+        AFC_OP_STATUS          = 0x00000001,    /* Status */
+        AFC_OP_DATA            = 0x00000002,    /* Data */
+        AFC_OP_READ_DIR        = 0x00000003,    /* ReadDir */
+        AFC_OP_READ_FILE       = 0x00000004,    /* ReadFile */
+        AFC_OP_WRITE_FILE      = 0x00000005,    /* WriteFile */
+        AFC_OP_WRITE_PART      = 0x00000006,    /* WritePart */
+        AFC_OP_TRUNCATE        = 0x00000007,    /* TruncateFile */
+        AFC_OP_REMOVE_PATH     = 0x00000008,    /* RemovePath */
+        AFC_OP_MAKE_DIR        = 0x00000009,    /* MakeDir */
+        AFC_OP_GET_FILE_INFO   = 0x0000000a,    /* GetFileInfo */
+        AFC_OP_GET_DEVINFO     = 0x0000000b,    /* GetDeviceInfo */
+        AFC_OP_WRITE_FILE_ATOM = 0x0000000c,    /* WriteFileAtomic (tmp file+rename) */
+        AFC_OP_FILE_OPEN       = 0x0000000d,    /* FileRefOpen */
+        AFC_OP_FILE_OPEN_RES   = 0x0000000e,    /* FileRefOpenResult */
+        AFC_OP_READ            = 0x0000000f,    /* FileRefRead */
+        AFC_OP_WRITE           = 0x00000010,    /* FileRefWrite */
+        AFC_OP_FILE_SEEK       = 0x00000011,    /* FileRefSeek */
+        AFC_OP_FILE_TELL       = 0x00000012,    /* FileRefTell */
+        AFC_OP_FILE_TELL_RES   = 0x00000013,    /* FileRefTellResult */
+        AFC_OP_FILE_CLOSE      = 0x00000014,    /* FileRefClose */
+        AFC_OP_FILE_SET_SIZE   = 0x00000015,    /* FileRefSetFileSize (ftruncate) */
+        AFC_OP_GET_CON_INFO    = 0x00000016,    /* GetConnectionInfo */
+        AFC_OP_SET_CON_OPTIONS = 0x00000017,    /* SetConnectionOptions */
+        AFC_OP_RENAME_PATH     = 0x00000018,    /* RenamePath */
+        AFC_OP_SET_FS_BS       = 0x00000019,    /* SetFSBlockSize (0x800000) */
+        AFC_OP_SET_SOCKET_BS   = 0x0000001A,    /* SetSocketBlockSize (0x800000) */
+        AFC_OP_FILE_LOCK       = 0x0000001B,    /* FileRefLock */
+        AFC_OP_MAKE_LINK       = 0x0000001C,    /* MakeLink */
+        AFC_OP_SET_FILE_TIME   = 0x0000001E     /* set st_mtime */
 };
 
diff --git a/src/device_link_service.h b/src/device_link_service.h
index c80686d..8b58ccf 100644
--- a/src/device_link_service.h
+++ b/src/device_link_service.h
@@ -32,12 +32,13 @@
 
 #define DEVICE_LINK_SERVICE_E_UNKNOWN_ERROR       -256
 
+/** Represents an error code. */
+typedef int16_t device_link_service_error_t;
 
 struct device_link_service_client_private {
         property_list_service_client_t parent;
 };
 
-typedef int16_t device_link_service_error_t;
 typedef struct device_link_service_client_private *device_link_service_client_t;
 
 device_link_service_error_t device_link_service_client_new(idevice_t device, uint16_t port, device_link_service_client_t *client);
diff --git a/src/idevice.c b/src/idevice.c
index 0bdf3f5..b72b623 100644
--- a/src/idevice.c
+++ b/src/idevice.c
@@ -172,7 +172,8 @@ idevice_error_t idevice_new(idevice_t * device, const char *uuid)
         return IDEVICE_E_NO_DEVICE;
 }
 
-/** Cleans up an idevice structure, then frees the structure itself.  
+/**
+ * Cleans up an idevice structure, then frees the structure itself.
  * This is a library-level function; deals directly with the device to tear
  *  down relations, but otherwise is mostly internal.
  * 
@@ -422,6 +423,9 @@ idevice_error_t idevice_connection_receive(idevice_connection_t connection, char
         return internal_connection_receive(connection, data, len, recv_bytes);
 }
 
+/**
+ * Gets the handle of the device. Depends on the connection type.
+ */
 idevice_error_t idevice_get_handle(idevice_t device, uint32_t *handle)
 {
         if (!device)
@@ -436,6 +440,9 @@ idevice_error_t idevice_get_handle(idevice_t device, uint32_t *handle)
         return IDEVICE_E_UNKNOWN_ERROR;
 }
 
+/**
+ * Gets the unique id for the device.
+ */
 idevice_error_t idevice_get_uuid(idevice_t device, char **uuid)
 {
         if (!device)
@@ -469,10 +476,10 @@ static ssize_t internal_ssl_read(gnutls_transport_ptr_t transport, char *buffer,
                 }
                 debug_info("post-read we got %i bytes", bytes);
 
-                // increase read count
+                /* increase read count */
                 tbytes += bytes;
 
-                // fill the buffer with what we got right now
+                /* fill the buffer with what we got right now */
                 memcpy(buffer + pos_start_fill, recv_buffer, bytes);
                 pos_start_fill += bytes;
 
@@ -538,7 +545,7 @@ idevice_error_t idevice_connection_enable_ssl(idevice_connection_t connection)
 
         ssl_data_t ssl_data_loc = (ssl_data_t)malloc(sizeof(struct ssl_data_private));
 
-        // Set up GnuTLS...
+        /* Set up GnuTLS... */
         debug_info("enabling SSL mode");
         errno = 0;
         gnutls_global_init();
@@ -558,7 +565,7 @@ idevice_error_t idevice_connection_enable_ssl(idevice_connection_t connection)
                 gnutls_protocol_set_priority(ssl_data_loc->session, protocol_priority);
                 gnutls_mac_set_priority(ssl_data_loc->session, mac_priority);
         }
-        gnutls_credentials_set(ssl_data_loc->session, GNUTLS_CRD_CERTIFICATE, ssl_data_loc->certificate); // this part is killing me.
+        gnutls_credentials_set(ssl_data_loc->session, GNUTLS_CRD_CERTIFICATE, ssl_data_loc->certificate); /* this part is killing me. */
 
         debug_info("GnuTLS step 1...");
         gnutls_transport_set_ptr(ssl_data_loc->session, (gnutls_transport_ptr_t)connection);
diff --git a/src/lockdown.c b/src/lockdown.c
index 25a6c6a..515c58e 100644
--- a/src/lockdown.c
+++ b/src/lockdown.c
@@ -1,6 +1,6 @@
 /*
  * lockdown.c
- * libimobiledevice built-in lockdownd client
+ * com.apple.mobile.lockdownd service implementation.
  *
  * Copyright (c) 2008 Zach C. All Rights Reserved.
  *
@@ -124,15 +124,14 @@ static void plist_dict_add_label(plist_t plist, const char *label)
 }
 
 /**
- * Closes the lockdownd communication session, by sending the StopSession
- * Request to the device.
+ * Closes the lockdownd session by sending the StopSession request.
  *
  * @see lockdownd_start_session
  *
- * @param control The lockdown client
+ * @param client The lockdown client
  * @param session_id The id of a running session
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
  */
 lockdownd_error_t lockdownd_stop_session(lockdownd_client_t client, const char *session_id)
 {
@@ -178,11 +177,13 @@ lockdownd_error_t lockdownd_stop_session(lockdownd_client_t client, const char *
         return ret;
 }
 
-/** Closes the lockdownd client and does the necessary housekeeping.
+/**
+ * Closes the lockdownd client session if one is running and frees up the
+ * lockdownd_client struct.
  *
  * @param client The lockdown client
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
  */
 lockdownd_error_t lockdownd_client_free(lockdownd_client_t client)
 {
@@ -229,12 +230,14 @@ void lockdownd_client_set_label(lockdownd_client_t client, const char *label)
         }
 }
 
-/** Polls the device for lockdownd data.
+/**
+ * Receives a plist from lockdownd.
  *
- * @param control The lockdownd client
+ * @param client The lockdownd client
  * @param plist The plist to store the received data
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client or
+ *  plist is NULL
  */
 lockdownd_error_t lockdownd_receive(lockdownd_client_t client, plist_t *plist)
 {
@@ -254,7 +257,8 @@ lockdownd_error_t lockdownd_receive(lockdownd_client_t client, plist_t *plist)
         return ret;
 }
 
-/** Sends lockdownd data to the device
+/**
+ * Sends a plist to lockdownd.
  *
  * @note This function is low-level and should only be used if you need to send
  *        a new type of message.
@@ -262,7 +266,8 @@ lockdownd_error_t lockdownd_receive(lockdownd_client_t client, plist_t *plist)
  * @param client The lockdownd client
  * @param plist The plist to send
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client or
+ *  plist is NULL
  */
 lockdownd_error_t lockdownd_send(lockdownd_client_t client, plist_t plist)
 {
@@ -279,13 +284,14 @@ lockdownd_error_t lockdownd_send(lockdownd_client_t client, plist_t plist)
         return ret;
 }
 
-/** Query the type of the service daemon. Depending on whether the device is
+/**
+ * Query the type of the service daemon. Depending on whether the device is
  * queried in normal mode or restore mode, different types will be returned.
  *
  * @param client The lockdownd client
- * @param type The type returned by the service daemon. Can be NULL to ignore.
+ * @param type The type returned by the service daemon. Pass NULL to ignore.
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
  */
 lockdownd_error_t lockdownd_query_type(lockdownd_client_t client, char **type)
 {
@@ -325,14 +331,15 @@ lockdownd_error_t lockdownd_query_type(lockdownd_client_t client, char **type)
         return ret;
 }
 
-/** Retrieves a preferences plist using an optional domain and/or key name.
+/**
+ * Retrieves a preferences plist using an optional domain and/or key name.
  *
- * @param client an initialized lockdownd client.
- * @param domain the domain to query on or NULL for global domain
- * @param key the key name to request or NULL to query for all keys
- * @param value a plist node representing the result value node
+ * @param client An initialized lockdownd client.
+ * @param domain The domain to query on or NULL for global domain
+ * @param key The key name to request or NULL to query for all keys
+ * @param value A plist node representing the result value node
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
  */
 lockdownd_error_t lockdownd_get_value(lockdownd_client_t client, const char *domain, const char *key, plist_t *value)
 {
@@ -387,14 +394,16 @@ lockdownd_error_t lockdownd_get_value(lockdownd_client_t client, const char *dom
         return ret;
 }
 
-/** Sets a preferences value using a plist and optional domain and/or key name.
+/**
+ * Sets a preferences value using a plist and optional by domain and/or key name.
  *
  * @param client an initialized lockdownd client.
  * @param domain the domain to query on or NULL for global domain
  * @param key the key name to set the value or NULL to set a value dict plist
  * @param value a plist node of any node type representing the value to set
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client or 
+ *  value is NULL
  */
 lockdownd_error_t lockdownd_set_value(lockdownd_client_t client, const char *domain, const char *key, plist_t value)
 {
@@ -444,15 +453,16 @@ lockdownd_error_t lockdownd_set_value(lockdownd_client_t client, const char *dom
         return ret;
 }
 
-/** Removes a preference node on the device by domain and/or key name
+/**
+ * Removes a preference node by domain and/or key name.
  *
  * @note: Use with caution as this could remove vital information on the device
  *
- * @param client an initialized lockdownd client.
- * @param domain the domain to query on or NULL for global domain
- * @param key the key name to remove or NULL remove all keys for the current domain
+ * @param client An initialized lockdownd client.
+ * @param domain The domain to query on or NULL for global domain
+ * @param key The key name to remove or NULL remove all keys for the current domain
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
  */
 lockdownd_error_t lockdownd_remove_value(lockdownd_client_t client, const char *domain, const char *key)
 {
@@ -501,9 +511,14 @@ lockdownd_error_t lockdownd_remove_value(lockdownd_client_t client, const char *
         return ret;
 }
 
-/** Asks for the device's unique id. Part of the lockdownd handshake.
+/**
+ * Returns the unique id of the device from lockdownd.
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @param client An initialized lockdownd client.
+ * @param uuid Holds the unique id of the device. The caller is responsible
+ *  for freeing the memory.
+ *
+ * @return LOCKDOWN_E_SUCCESS on success
  */
 lockdownd_error_t lockdownd_get_device_uuid(lockdownd_client_t client, char **uuid)
 {
@@ -521,9 +536,14 @@ lockdownd_error_t lockdownd_get_device_uuid(lockdownd_client_t client, char **uu
         return ret;
 }
 
-/** Askes for the device's public key. Part of the lockdownd handshake.
+/**
+ * Retrieves the public key of the device from lockdownd.
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @param client An initialized lockdownd client.
+ * @param public_key Holds the public key of the device. The caller is
+ *  responsible for freeing the memory.
+ *
+ * @return LOCKDOWN_E_SUCCESS on success
  */
 lockdownd_error_t lockdownd_get_device_public_key(lockdownd_client_t client, gnutls_datum_t * public_key)
 {
@@ -546,12 +566,14 @@ lockdownd_error_t lockdownd_get_device_public_key(lockdownd_client_t client, gnu
         return ret;
 }
 
-/** Askes for the device's name.
- *
- * @param client The pointer to the location of the new lockdownd_client
+/**
+ * Retrieves the name of the device from lockdownd set by the user.
  *
+ * @param client An initialized lockdownd client.
+ * @param device_name Holds the name of the device. The caller is
+ *  responsible for freeing the memory.
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success
  */
 lockdownd_error_t lockdownd_get_device_name(lockdownd_client_t client, char **device_name)
 {
@@ -570,13 +592,17 @@ lockdownd_error_t lockdownd_get_device_name(lockdownd_client_t client, char **de
         return ret;
 }
 
-/** Creates a lockdownd client for the device.
+/**
+ * Creates a new lockdownd client for the device.
  *
- * @param phone The device to create a lockdownd client for
+ * @note This function does not pair with the device or start a session. This
+ *  has to be done manually by the caller after the client is created.
+ *
+ * @param device The device to create a lockdownd client for
  * @param client The pointer to the location of the new lockdownd_client
- * @param label The label to use for communication. Usually the program name
+ * @param label The label to use for communication. Usually the program name.
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
  */
 lockdownd_error_t lockdownd_client_new(idevice_t device, lockdownd_client_t *client, const char *label)
 {
@@ -609,15 +635,18 @@ lockdownd_error_t lockdownd_client_new(idevice_t device, lockdownd_client_t *cli
         return ret;
 }
 
-/** Creates a lockdownd client for the device and starts initial handshake.
- * The handshake consists of query_type, validate_pair, pair and
- * start_session calls.
+/**
+ * Creates a new lockdownd client for the device and starts initial handshake.
+ * The handshake consists out of query_type, validate_pair, pair and
+ * start_session calls. It uses the internal pairing record management.
  *
- * @param phone The device to create a lockdownd client for
+ * @param device The device to create a lockdownd client for
  * @param client The pointer to the location of the new lockdownd_client
- * @param label The label to use for communication. Usually the program name
+ * @param label The label to use for communication. Usually the program name.
+ *  Pass NULL to disable sending the label in requests to lockdownd.
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL,
+ *  LOCKDOWN_E_INVALID_CONF if configuration data is wrong
  */
 lockdownd_error_t lockdownd_client_new_with_handshake(idevice_t device, lockdownd_client_t *client, const char *label)
 {
@@ -690,6 +719,14 @@ lockdownd_error_t lockdownd_client_new_with_handshake(idevice_t device, lockdown
         return ret;
 }
 
+/**
+ * Returns a new plist from the supplied lockdownd pair record. The caller is
+ * responsible for freeing the plist.
+ *
+ * @param pair_record The pair record to create a plist from.
+ *
+ * @return A pair record plist from the device, NULL if pair_record is not set
+ */
 static plist_t lockdownd_pair_record_to_plist(lockdownd_pair_record_t pair_record)
 {
         if (!pair_record)
@@ -712,6 +749,17 @@ static plist_t lockdownd_pair_record_to_plist(lockdownd_pair_record_t pair_recor
         return dict;
 }
 
+/**
+ * Generates a new pairing record plist and required certificates for the 
+ * supplied public key of the device and the host_id of the caller's host
+ * computer.
+ *
+ * @param public_key The public key of the device.
+ * @param host_id The HostID to use for the pair record plist.
+ * @param pair_record_plist Holds the generated pair record.
+ *
+ * @return LOCKDOWN_E_SUCCESS on success
+ */
 static lockdownd_error_t generate_pair_record_plist(gnutls_datum_t public_key, char *host_id, plist_t *pair_record_plist)
 {
         lockdownd_error_t ret = LOCKDOWN_E_UNKNOWN_ERROR;
@@ -743,7 +791,8 @@ static lockdownd_error_t generate_pair_record_plist(gnutls_datum_t public_key, c
         return ret;
 }
 
-/** Function used internally by lockdownd_pair() and lockdownd_validate_pair()
+/**
+ * Function used internally by lockdownd_pair() and lockdownd_validate_pair()
  *
  * @param client The lockdown client to pair with.
  * @param pair_record The pair record to use for pairing. If NULL is passed, then
@@ -751,10 +800,17 @@ static lockdownd_error_t generate_pair_record_plist(gnutls_datum_t public_key, c
  *    generated automatically when pairing is done for the first time.
  * @param verb This is either "Pair", "ValidatePair" or "Unpair".
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL,
+ *  LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong,
+ *  LOCKDOWN_E_PAIRING_FAILED if the pairing failed,
+ *  LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected,
+ *  LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id
  */
 static lockdownd_error_t lockdownd_do_pair(lockdownd_client_t client, lockdownd_pair_record_t pair_record, const char *verb)
 {
+        if (!client)
+                return LOCKDOWN_E_INVALID_ARG;
+
         lockdownd_error_t ret = LOCKDOWN_E_UNKNOWN_ERROR;
         plist_t dict = NULL;
         plist_t dict_record = NULL;
@@ -855,15 +911,18 @@ static lockdownd_error_t lockdownd_do_pair(lockdownd_client_t client, lockdownd_
 }
 
 /** 
- * Pairs the device with the given HostID.
- * It's part of the lockdownd handshake.
+ * Pairs the device using the supplied pair record.
  *
  * @param client The lockdown client to pair with.
  * @param pair_record The pair record to use for pairing. If NULL is passed, then
  *    the pair records from the current machine are used. New records will be
  *    generated automatically when pairing is done for the first time.
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL,
+ *  LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong,
+ *  LOCKDOWN_E_PAIRING_FAILED if the pairing failed,
+ *  LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected,
+ *  LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id
  */
 lockdownd_error_t lockdownd_pair(lockdownd_client_t client, lockdownd_pair_record_t pair_record)
 {
@@ -871,17 +930,21 @@ lockdownd_error_t lockdownd_pair(lockdownd_client_t client, lockdownd_pair_recor
 }
 
 /** 
- * Pairs the device with the given HostID. The difference to lockdownd_pair()
- * is that the specified host will become trusted host of the device.
- * It's part of the lockdownd handshake.
+ * Validates if the device is paired with the given HostID. If succeeded them
+ * specified host will become trusted host of the device indicated by the 
+ * lockdownd preference named TrustedHostAttached. Otherwise the host must because
+ * paired using lockdownd_pair() first.
  *
  * @param client The lockdown client to pair with.
  * @param pair_record The pair record to validate pairing with. If NULL is
- *    passed, then the pair records from the current machine are used.
- *    New records will be generated automatically when pairing is done
- *    for the first time.
+ *    passed, then the pair record is read from the internal pairing record
+ *    management.
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL,
+ *  LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong,
+ *  LOCKDOWN_E_PAIRING_FAILED if the pairing failed,
+ *  LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected,
+ *  LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id
  */
 lockdownd_error_t lockdownd_validate_pair(lockdownd_client_t client, lockdownd_pair_record_t pair_record)
 {
@@ -890,13 +953,17 @@ lockdownd_error_t lockdownd_validate_pair(lockdownd_client_t client, lockdownd_p
 
 /** 
  * Unpairs the device with the given HostID and removes the pairing records
- * from the device and host.
+ * from the device and host if the internal pairing record management is used.
  *
  * @param client The lockdown client to pair with.
  * @param pair_record The pair record to use for unpair. If NULL is passed, then
  *    the pair records from the current machine are used.
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL,
+ *  LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong,
+ *  LOCKDOWN_E_PAIRING_FAILED if the pairing failed,
+ *  LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected,
+ *  LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id
  */
 lockdownd_error_t lockdownd_unpair(lockdownd_client_t client, lockdownd_pair_record_t pair_record)
 {
@@ -908,7 +975,7 @@ lockdownd_error_t lockdownd_unpair(lockdownd_client_t client, lockdownd_pair_rec
  *
  * @param client The lockdown client
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL
  */
 lockdownd_error_t lockdownd_enter_recovery(lockdownd_client_t client)
 {
@@ -939,12 +1006,12 @@ lockdownd_error_t lockdownd_enter_recovery(lockdownd_client_t client)
 }
 
 /**
- * Performs the Goodbye Request to tell the device the communication
- * session is now closed.
+ * Sends the Goodbye request to lockdownd signaling the end of communication.
  *
  * @param client The lockdown client
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL,
+ *  LOCKDOWN_E_PLIST_ERROR if the device did not acknowledge the request
  */
 lockdownd_error_t lockdownd_goodbye(lockdownd_client_t client)
 {
@@ -978,10 +1045,18 @@ lockdownd_error_t lockdownd_goodbye(lockdownd_client_t client)
         return ret;
 }
 
-/** Generates the device certificate from the public key as well as the host
- *  and root certificates.
+/**
+ * Generates the device certificate from the public key as well as the host
+ * and root certificates.
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @param public_key The public key of the device to use for generation.
+ * @param odevice_cert Holds the generated device certificate.
+ * @param ohost_cert Holds the generated host certificate.
+ * @param oroot_cert Holds the generated root certificate.
+ *
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when a parameter is NULL,
+ *  LOCKDOWN_E_INVALID_CONF if the internal configuration system failed,
+ *  LOCKDOWN_E_SSL_ERROR if the certificates could not be generated
  */
 lockdownd_error_t lockdownd_gen_pair_cert(gnutls_datum_t public_key, gnutls_datum_t * odevice_cert,
                                                                            gnutls_datum_t * ohost_cert, gnutls_datum_t * oroot_cert)
@@ -1116,15 +1191,18 @@ lockdownd_error_t lockdownd_gen_pair_cert(gnutls_datum_t public_key, gnutls_datu
         return ret;
 }
 
-/** Starts communication with lockdownd after the device has been paired,
- *  and if the device requires it, switches to SSL mode.
+/**
+ * Opens a session with lockdownd and switches to SSL mode if device wants it.
  *
  * @param client The lockdownd client
  * @param host_id The HostID of the computer
- * @param session_id The session_id of the created session
+ * @param session_id The new session_id of the created session
  * @param ssl_enabled Whether SSL communication is used in the session
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when a client or
+ *  host_id is NULL, LOCKDOWN_E_PLIST_ERROR if the response plist had errors,
+ *  LOCKDOWN_E_INVALID_HOST_ID if the device does not know the supplied HostID,
+ *  LOCKDOWN_E_SSL_ERROR if enabling SSL communication failed
  */
 lockdownd_error_t lockdownd_start_session(lockdownd_client_t client, const char *host_id, char **session_id, int *ssl_enabled)
 {
@@ -1212,13 +1290,17 @@ lockdownd_error_t lockdownd_start_session(lockdownd_client_t client, const char
         return ret;
 }
 
-/** Command to start the desired service
+/**
+ * Requests to start a service and retrieve it's port on success.
  *
  * @param client The lockdownd client
  * @param service The name of the service to start
  * @param port The port number the service was started on
  
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG if a parameter
+ *  is NULL, LOCKDOWN_E_INVALID_SERVICE if the requested service is not known
+ *  by the device, LOCKDOWN_E_START_SERVICE_FAILED if the service could not because
+ *  started by the device
  */
 lockdownd_error_t lockdownd_start_service(lockdownd_client_t client, const char *service, uint16_t *port)
 {
@@ -1300,10 +1382,15 @@ lockdownd_error_t lockdownd_start_service(lockdownd_client_t client, const char
  *
  * @see http://iphone-docs.org/doku.php?id=docs:protocols:activation
  *
- * @param control The lockdown client
+ * @param client The lockdown client
  * @param activation_record The activation record plist dictionary
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client or
+ *  activation_record is NULL, LOCKDOWN_E_NO_RUNNING_SESSION if no session is
+ *  open, LOCKDOWN_E_PLIST_ERROR if the received plist is broken, 
+ *  LOCKDOWN_E_ACTIVATION_FAILED if the activation failed, 
+ *  LOCKDOWN_E_INVALID_ACTIVATION_RECORD if the device reports that the
+ *  activation_record is invalid
  */
 lockdownd_error_t lockdownd_activate(lockdownd_client_t client, plist_t activation_record) 
 {
@@ -1357,12 +1444,14 @@ lockdownd_error_t lockdownd_activate(lockdownd_client_t client, plist_t activati
 }
 
 /**
- * Deactivates the device, returning it to the locked
- * “Activate with iTunes” screen.
+ * Deactivates the device, returning it to the locked “Activate with iTunes”
+ * screen.
  *
- * @param control The lockdown client
+ * @param client The lockdown client
  *
- * @return an error code (LOCKDOWN_E_SUCCESS on success)
+ * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL,
+ *  LOCKDOWN_E_NO_RUNNING_SESSION if no session is open, 
+ *  LOCKDOWN_E_PLIST_ERROR if the received plist is broken
  */
 lockdownd_error_t lockdownd_deactivate(lockdownd_client_t client)
 {
diff --git a/src/mobilebackup.c b/src/mobilebackup.c
index c5f0a84..15da0a1 100644
--- a/src/mobilebackup.c
+++ b/src/mobilebackup.c
@@ -59,6 +59,18 @@ static mobilebackup_error_t mobilebackup_error(device_link_service_error_t err)
         return MOBILEBACKUP_E_UNKNOWN_ERROR;
 }
 
+/**
+ * Connects to the mobilebackup service on the specified device.
+ *
+ * @param device The device to connect to.
+ * @param port Destination port (usually given by lockdownd_start_service).
+ * @param client Pointer that will be set to a newly allocated
+ *     mobilebackup_client_t upon successful return.
+ *
+ * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID ARG if one
+ *     or more parameters are invalid, or DEVICE_LINK_SERVICE_E_BAD_VERSION if
+ *     the mobilebackup version on the device is newer.
+ */
 mobilebackup_error_t mobilebackup_client_new(idevice_t device, uint16_t port,
                                                    mobilebackup_client_t * client)
 {
@@ -87,6 +99,15 @@ mobilebackup_error_t mobilebackup_client_new(idevice_t device, uint16_t port,
         return ret;
 }
 
+/**
+ * Disconnects a mobilebackup client from the device and frees up the
+ * mobilebackup client data.
+ *
+ * @param client The mobilebackup client to disconnect and free.
+ *
+ * @return MOBILEBACKUP_E_SUCCESS on success, or MOBILEBACKUP_E_INVALID_ARG
+ *     if client is NULL.
+ */
 mobilebackup_error_t mobilebackup_client_free(mobilebackup_client_t client)
 {
         if (!client)
@@ -97,9 +118,10 @@ mobilebackup_error_t mobilebackup_client_free(mobilebackup_client_t client)
         return err;
 }
 
-/** Polls the device for MobileBackup data.
+/**
+ * Polls the device for mobilebackup data.
  *
- * @param client The MobileBackup client
+ * @param client The mobilebackup client
  * @param plist A pointer to the location where the plist should be stored
  *
  * @return an error code
@@ -112,12 +134,13 @@ mobilebackup_error_t mobilebackup_receive(mobilebackup_client_t client, plist_t
         return ret;
 }
 
-/** Sends MobileBackup data to the device
+/**
+ * Sends mobilebackup data to the device
  * 
  * @note This function is low-level and should only be used if you need to send
  *        a new type of message.
  *
- * @param client The MobileBackup client
+ * @param client The mobilebackup client
  * @param plist The location of the plist to send
  *
  * @return an error code
diff --git a/src/mobilesync.c b/src/mobilesync.c
index 88d8497..47fcfdf 100644
--- a/src/mobilesync.c
+++ b/src/mobilesync.c
@@ -59,6 +59,18 @@ static mobilesync_error_t mobilesync_error(device_link_service_error_t err)
         return MOBILESYNC_E_UNKNOWN_ERROR;
 }
 
+/**
+ * Connects to the mobilesync service on the specified device.
+ *
+ * @param device The device to connect to.
+ * @param port Destination port (usually given by lockdownd_start_service).
+ * @param client Pointer that will be set to a newly allocated
+ *     mobilesync_client_t upon successful return.
+ *
+ * @return MOBILESYNC_E_SUCCESS on success, MOBILESYNC_E_INVALID ARG if one
+ *     or more parameters are invalid, or DEVICE_LINK_SERVICE_E_BAD_VERSION if
+ *     the mobilesync version on the device is newer.
+ */
 mobilesync_error_t mobilesync_client_new(idevice_t device, uint16_t port,
                                                    mobilesync_client_t * client)
 {
@@ -87,6 +99,15 @@ mobilesync_error_t mobilesync_client_new(idevice_t device, uint16_t port,
         return ret;
 }
 
+/**
+ * Disconnects a mobilesync client from the device and frees up the
+ * mobilesync client data.
+ *
+ * @param client The mobilesync client to disconnect and free.
+ *
+ * @return MOBILESYNC_E_SUCCESS on success, or MOBILESYNC_E_INVALID_ARG
+ *     if client is NULL.
+ */
 mobilesync_error_t mobilesync_client_free(mobilesync_client_t client)
 {
         if (!client)
@@ -97,9 +118,10 @@ mobilesync_error_t mobilesync_client_free(mobilesync_client_t client)
         return err;
 }
 
-/** Polls the device for MobileSync data.
+/**
+ * Polls the device for mobilesync data.
  *
- * @param client The MobileSync client
+ * @param client The mobilesync client
  * @param plist A pointer to the location where the plist should be stored
  *
  * @return an error code
@@ -112,12 +134,13 @@ mobilesync_error_t mobilesync_receive(mobilesync_client_t client, plist_t * plis
         return ret;
 }
 
-/** Sends MobileSync data to the device
+/**
+ * Sends mobilesync data to the device
  * 
  * @note This function is low-level and should only be used if you need to send
  *        a new type of message.
  *
- * @param client The MobileSync client
+ * @param client The mobilesync client
  * @param plist The location of the plist to send
  *
  * @return an error code
diff --git a/src/sbservices.c b/src/sbservices.c
index 91f4b9c..076e25d 100644
--- a/src/sbservices.c
+++ b/src/sbservices.c
@@ -208,7 +208,7 @@ sbservices_error_t sbservices_set_icon_state(sbservices_client_t client, plist_t
         if (res != SBSERVICES_E_SUCCESS) {
                 debug_info("could not send plist, error %d", res);
         }
-        // NO RESPONSE
+        /* NO RESPONSE */
 
         if (dict) {
                 plist_free(dict);
diff --git a/src/screenshotr.h b/src/screenshotr.h
index 5ba93b0..df6774a 100644
--- a/src/screenshotr.h
+++ b/src/screenshotr.h
@@ -1,4 +1,4 @@
-/* 
+/*
  * screenshotr.h
  * com.apple.mobile.screenshotr service header file.
  * 
diff --git a/src/userpref.c b/src/userpref.c
index 3a8a9d6..59c61b6 100644
--- a/src/userpref.c
+++ b/src/userpref.c
@@ -42,7 +42,8 @@
 #define LIBIMOBILEDEVICE_HOST_CERTIF "HostCertificate.pem"
 
 
-/** Creates a freedesktop compatible configuration directory.
+/**
+ * Creates a freedesktop compatible configuration directory.
  */
 static void userpref_create_config_dir(void)
 {
@@ -60,7 +61,8 @@ static int get_rand(int min, int max)
         return retval;
 }
 
-/** Generates a valid HostID (which is actually a UUID).
+/**
+ * Generates a valid HostID (which is actually a UUID).
  *
  * @return A null terminated string containing a valid HostID.
  */
@@ -85,7 +87,8 @@ static char *userpref_generate_host_id()
         return hostid;
 }
 
-/** Store HostID in config file.
+/**
+ * Store HostID in config file.
  *
  * @param host_id A null terminated string containing a valid HostID.
  */
@@ -123,7 +126,8 @@ static int userpref_set_host_id(const char *host_id)
         return 1;
 }
 
-/** Reads the HostID from a previously generated configuration file.
+/**
+ * Reads the HostID from a previously generated configuration file.
  *
  * @note It is the responsibility of the calling function to free the returned host_id
  *
@@ -158,7 +162,8 @@ void userpref_get_host_id(char **host_id)
         debug_info("Using %s as HostID", *host_id);
 }
 
-/** Determines whether this device has been connected to this system before.
+/**
+ * Determines whether this device has been connected to this system before.
  *
  * @param uid The device uid as given by the device.
  *
@@ -180,8 +185,9 @@ int userpref_has_device_public_key(const char *uuid)
         return ret;
 }
 
-/** Mark the device (as represented by the key) as having connected to this
- *  configuration.
+/**
+ * Mark the device (as represented by the key) as having connected to this
+ * configuration.
  *
  * @param public_key The public key given by the device
  *
@@ -213,7 +219,8 @@ userpref_error_t userpref_set_device_public_key(const char *uuid, gnutls_datum_t
         return USERPREF_E_SUCCESS;
 }
 
-/** Remove the public key stored for the device with uuid from this host.
+/**
+ * Remove the public key stored for the device with uuid from this host.
  *
  * @param uuid The uuid of the device
  *
@@ -237,7 +244,8 @@ userpref_error_t userpref_remove_device_public_key(const char *uuid)
         return USERPREF_E_SUCCESS;
 }
 
-/** Private function which reads the given file into a gnutls structure.
+/**
+ * Private function which reads the given file into a gnutls structure.
  *
  * @param file The filename of the file to read
  * @param data The pointer at which to store the data.
@@ -266,7 +274,8 @@ static int userpref_get_file_contents(const char *file, gnutls_datum_t * data)
         return success;
 }
 
-/** Private function which generate private keys and certificates.
+/**
+ * Private function which generate private keys and certificates.
  *
  * @return 1 if keys were successfully generated, 0 otherwise
  */
@@ -365,7 +374,8 @@ static userpref_error_t userpref_gen_keys_and_cert(void)
         return ret;
 }
 
-/** Private function which import the given key into a gnutls structure.
+/**
+ * Private function which import the given key into a gnutls structure.
  *
  * @param key_name The filename of the private key to import.
  * @param key the gnutls key structure.
@@ -387,7 +397,8 @@ static userpref_error_t userpref_import_key(const char* key_name, gnutls_x509_pr
         return ret;
 }
 
-/** Private function which import the given certificate into a gnutls structure.
+/**
+ * Private function which import the given certificate into a gnutls structure.
  *
  * @param crt_name The filename of the certificate to import.
  * @param cert the gnutls certificate structure.
@@ -409,7 +420,8 @@ static userpref_error_t userpref_import_crt(const char* crt_name, gnutls_x509_cr
         return ret;
 }
 
-/** Function to retrieve host keys and certificates.
+/**
+ * Function to retrieve host keys and certificates.
  * This function trigger key generation if they do not exists yet or are invalid.
  *
  * @note This function can take few seconds to complete (typically 5 seconds)
@@ -459,7 +471,8 @@ userpref_error_t userpref_get_keys_and_certs(gnutls_x509_privkey_t root_privkey,
         return ret;
 }
 
-/** Function to retrieve certificates encoded in PEM format.
+/**
+ * Function to retrieve certificates encoded in PEM format.
  *
  * @param pem_root_cert The root certificate.
  * @param pem_host_cert The host certificate.
@@ -480,7 +493,8 @@ userpref_error_t userpref_get_certs_as_pem(gnutls_datum_t *pem_root_cert, gnutls
         return USERPREF_E_INVALID_CONF;
 }
 
-/** Create and save a configuration file containing the given data.
+/**
+ * Create and save a configuration file containing the given data.
  *
  * @note: All fields must specified and be non-null
  *