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.

21 files changed, 502 insertions, 268 deletions

diff --git a/include/libimobiledevice/afc.h b/include/libimobiledevice/afc.h
index d800d19..c060eb7 100644
--- a/include/libimobiledevice/afc.h
+++ b/include/libimobiledevice/afc.h
@@ -29,7 +29,8 @@ extern "C" {
 
 #include <libimobiledevice/libimobiledevice.h>
 
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
 #define AFC_E_SUCCESS                 0
 #define AFC_E_UNKNOWN_ERROR           1
 #define AFC_E_OP_HEADER_INVALID       2
@@ -59,28 +60,32 @@ extern "C" {
 #define AFC_E_NO_MEM                 31
 #define AFC_E_NOT_ENOUGH_DATA        32
 #define AFC_E_DIR_NOT_EMPTY          33
+/*@}*/
 
+/** Represents an error code. */
 typedef int16_t afc_error_t;
 
-/* Flags */
+/** Flags for afc_file_open */
 typedef enum {
-	AFC_FOPEN_RDONLY   = 0x00000001, // r   O_RDONLY
-	AFC_FOPEN_RW       = 0x00000002, // r+  O_RDWR   | O_CREAT
-	AFC_FOPEN_WRONLY   = 0x00000003, // w   O_WRONLY | O_CREAT  | O_TRUNC
-	AFC_FOPEN_WR       = 0x00000004, // w+  O_RDWR   | O_CREAT  | O_TRUNC
-	AFC_FOPEN_APPEND   = 0x00000005, // a   O_WRONLY | O_APPEND | O_CREAT
-	AFC_FOPEN_RDAPPEND = 0x00000006  // a+  O_RDWR   | O_APPEND | O_CREAT
+	AFC_FOPEN_RDONLY   = 0x00000001, /**< r   O_RDONLY */
+	AFC_FOPEN_RW       = 0x00000002, /**< r+  O_RDWR   | O_CREAT */
+	AFC_FOPEN_WRONLY   = 0x00000003, /**< w   O_WRONLY | O_CREAT  | O_TRUNC */
+	AFC_FOPEN_WR       = 0x00000004, /**< w+  O_RDWR   | O_CREAT  | O_TRUNC */
+	AFC_FOPEN_APPEND   = 0x00000005, /**< a   O_WRONLY | O_APPEND | O_CREAT */
+	AFC_FOPEN_RDAPPEND = 0x00000006  /**< a+  O_RDWR   | O_APPEND | O_CREAT */
 } afc_file_mode_t;
 
+/** Type of link for afc_make_link() calls */
 typedef enum {
 	AFC_HARDLINK = 1,
 	AFC_SYMLINK = 2
 } afc_link_type_t;
 
+/** Lock operation flags */
 typedef enum {
-	AFC_LOCK_SH = 1 | 4, // shared lock
-	AFC_LOCK_EX = 2 | 4, // exclusive lock
-	AFC_LOCK_UN = 8 | 4  // unlock
+	AFC_LOCK_SH = 1 | 4, /**< shared lock */
+	AFC_LOCK_EX = 2 | 4, /**< exclusive lock */
+	AFC_LOCK_UN = 8 | 4  /**< unlock */
 } afc_lock_op_t;
 
 typedef struct afc_client_private afc_client_private;
diff --git a/include/libimobiledevice/file_relay.h b/include/libimobiledevice/file_relay.h
index dd65b38..b3900db 100644
--- a/include/libimobiledevice/file_relay.h
+++ b/include/libimobiledevice/file_relay.h
@@ -29,7 +29,8 @@ extern "C" {
 
 #include <libimobiledevice/libimobiledevice.h>
 
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
 #define FILE_RELAY_E_SUCCESS                0
 #define FILE_RELAY_E_INVALID_ARG           -1
 #define FILE_RELAY_E_PLIST_ERROR           -2
@@ -38,7 +39,9 @@ extern "C" {
 #define FILE_RELAY_E_STAGING_EMPTY         -5
 
 #define FILE_RELAY_E_UNKNOWN_ERROR       -256
+/*@}*/
 
+/** Represents an error code. */
 typedef int16_t file_relay_error_t;
 
 typedef struct file_relay_client_private file_relay_client_private;
diff --git a/include/libimobiledevice/installation_proxy.h b/include/libimobiledevice/installation_proxy.h
index 8a7cfb9..2bf738d 100644
--- a/include/libimobiledevice/installation_proxy.h
+++ b/include/libimobiledevice/installation_proxy.h
@@ -30,7 +30,8 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <glib.h>
 
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
 #define INSTPROXY_E_SUCCESS                0
 #define INSTPROXY_E_INVALID_ARG           -1
 #define INSTPROXY_E_PLIST_ERROR           -2
@@ -39,12 +40,15 @@ extern "C" {
 #define INSTPROXY_E_OP_FAILED             -5
 
 #define INSTPROXY_E_UNKNOWN_ERROR       -256
+/*@}*/
 
+/** Represents an error code. */
 typedef int16_t instproxy_error_t;
 
 typedef struct instproxy_client_private instproxy_client_private;
 typedef instproxy_client_private *instproxy_client_t; /**< The client handle. */
 
+/** Reports the status of the given operation */
 typedef void (*instproxy_status_cb_t) (const char *operation, plist_t status);
 
 /* Interface */
diff --git a/include/libimobiledevice/libimobiledevice.h b/include/libimobiledevice/libimobiledevice.h
index 73e82fe..0c6a08f 100644
--- a/include/libimobiledevice/libimobiledevice.h
+++ b/include/libimobiledevice/libimobiledevice.h
@@ -1,6 +1,6 @@
 /**
  * @file libimobiledevice/libimobiledevice.h
- * @brief Common code and device handling
+ * @brief Device/Connection handling and communication
  * \internal
  *
  * Copyright (c) 2008 Jonathan Beck All Rights Reserved.
@@ -32,7 +32,8 @@ extern "C" {
 #include <sys/stat.h>
 #include <plist/plist.h>
 
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
 #define IDEVICE_E_SUCCESS                0
 #define IDEVICE_E_INVALID_ARG           -1
 #define IDEVICE_E_UNKNOWN_ERROR         -2
@@ -40,7 +41,9 @@ extern "C" {
 #define IDEVICE_E_NOT_ENOUGH_DATA       -4
 #define IDEVICE_E_BAD_HEADER            -5
 #define IDEVICE_E_SSL_ERROR             -6
+/*@}*/
 
+/** Represents an error code. */
 typedef int16_t idevice_error_t;
 
 typedef struct idevice_private idevice_private;
@@ -53,23 +56,25 @@ typedef idevice_connection_private *idevice_connection_t; /**< The connection ha
 void idevice_set_debug_level(int level);
 
 /* discovery (events/asynchronous) */
-// event type
+/** The event type for device add or removal */
 enum idevice_event_type {
 	IDEVICE_DEVICE_ADD = 1,
 	IDEVICE_DEVICE_REMOVE
 };
 
-// event data structure
+/* event data structure */
+/** Provides information about the occoured event. */
 typedef struct {
-	enum idevice_event_type event;
-	const char *uuid;
-	int conn_type;
+	enum idevice_event_type event; /**< The event type. */
+	const char *uuid; /**< The device unique id. */
+	int conn_type; /**< The connection type. Currently only 1 for usbmuxd. */
 } idevice_event_t;
 
-// event callback function prototype
+/* event callback function prototype */
+/** Callback to notifiy if a device was added or removed. */
 typedef void (*idevice_event_cb_t) (const idevice_event_t *event, void *user_data);
 
-// functions
+/* functions */
 idevice_error_t idevice_event_subscribe(idevice_event_cb_t callback, void *user_data);
 idevice_error_t idevice_event_unsubscribe();
 
diff --git a/include/libimobiledevice/lockdown.h b/include/libimobiledevice/lockdown.h
index 6abf6d6..4504ef1 100644
--- a/include/libimobiledevice/lockdown.h
+++ b/include/libimobiledevice/lockdown.h
@@ -1,6 +1,6 @@
 /**
  * @file libimobiledevice/lockdown.h
- * @brief Communcation with the lockdown device daemon
+ * @brief Implementation to communicate with the lockdown device daemon
  * \internal
  *
  * Copyright (c) 2008 Zach C. All Rights Reserved.
@@ -30,7 +30,8 @@ extern "C" {
 
 #include <libimobiledevice/libimobiledevice.h>
 
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
 #define LOCKDOWN_E_SUCCESS                     0
 #define LOCKDOWN_E_INVALID_ARG                -1
 #define LOCKDOWN_E_INVALID_CONF               -2
@@ -52,18 +53,21 @@ extern "C" {
 #define LOCKDOWN_E_INVALID_ACTIVATION_RECORD -18
 
 #define LOCKDOWN_E_UNKNOWN_ERROR            -256
+/*@}*/
 
+/** Represents an error code. */
 typedef int16_t lockdownd_error_t;
 
 typedef struct lockdownd_client_private lockdownd_client_private;
 typedef lockdownd_client_private *lockdownd_client_t; /**< The client handle. */
 
 struct lockdownd_pair_record {
-	char *device_certificate;
-	char *host_certificate;
-	char *host_id;
-	char *root_certificate;
+	char *device_certificate; /**< The device certificate */
+	char *host_certificate;   /**< The host certificate */
+	char *host_id;            /**< A unique HostID for the host computer */
+	char *root_certificate;   /**< The root certificate */
 };
+/** A pair record holding device, host and root certificates along the host_id */
 typedef struct lockdownd_pair_record *lockdownd_pair_record_t;
 
 /* Interface */
diff --git a/include/libimobiledevice/mobile_image_mounter.h b/include/libimobiledevice/mobile_image_mounter.h
index 5681d8b..26a3666 100644
--- a/include/libimobiledevice/mobile_image_mounter.h
+++ b/include/libimobiledevice/mobile_image_mounter.h
@@ -29,14 +29,17 @@ extern "C" {
 
 #include <libimobiledevice/libimobiledevice.h>
 
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
 #define MOBILE_IMAGE_MOUNTER_E_SUCCESS                0
 #define MOBILE_IMAGE_MOUNTER_E_INVALID_ARG           -1
 #define MOBILE_IMAGE_MOUNTER_E_PLIST_ERROR           -2
 #define MOBILE_IMAGE_MOUNTER_E_CONN_FAILED           -3
 
 #define MOBILE_IMAGE_MOUNTER_E_UNKNOWN_ERROR       -256
+/*@}*/
 
+/** Represents an error code. */
 typedef int16_t mobile_image_mounter_error_t;
 
 typedef struct mobile_image_mounter_client_private mobile_image_mounter_client_private;
diff --git a/include/libimobiledevice/mobilebackup.h b/include/libimobiledevice/mobilebackup.h
index d6f9013..6f37a14 100644
--- a/include/libimobiledevice/mobilebackup.h
+++ b/include/libimobiledevice/mobilebackup.h
@@ -29,7 +29,8 @@ extern "C" {
 
 #include <libimobiledevice/libimobiledevice.h>
 
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
 #define MOBILEBACKUP_E_SUCCESS                0
 #define MOBILEBACKUP_E_INVALID_ARG           -1
 #define MOBILEBACKUP_E_PLIST_ERROR           -2
@@ -38,7 +39,9 @@ extern "C" {
 #define MOBILEBACKUP_E_REPLY_NOT_OK          -5
 
 #define MOBILEBACKUP_E_UNKNOWN_ERROR       -256
+/*@}*/
 
+/** Represents an error code. */
 typedef int16_t mobilebackup_error_t;
 
 typedef struct mobilebackup_client_private mobilebackup_client_private;
diff --git a/include/libimobiledevice/mobilesync.h b/include/libimobiledevice/mobilesync.h
index 2e330ee..7af3aef 100644
--- a/include/libimobiledevice/mobilesync.h
+++ b/include/libimobiledevice/mobilesync.h
@@ -29,7 +29,8 @@ extern "C" {
 
 #include <libimobiledevice/libimobiledevice.h>
 
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
 #define MOBILESYNC_E_SUCCESS                0
 #define MOBILESYNC_E_INVALID_ARG           -1
 #define MOBILESYNC_E_PLIST_ERROR           -2
@@ -37,7 +38,9 @@ extern "C" {
 #define MOBILESYNC_E_BAD_VERSION           -4
 
 #define MOBILESYNC_E_UNKNOWN_ERROR       -256
+/*@}*/
 
+/** Represents an error code. */
 typedef int16_t mobilesync_error_t;
 
 typedef struct mobilesync_client_private mobilesync_client_private;
diff --git a/include/libimobiledevice/notification_proxy.h b/include/libimobiledevice/notification_proxy.h
index 74b6b37..d85f56c 100644
--- a/include/libimobiledevice/notification_proxy.h
+++ b/include/libimobiledevice/notification_proxy.h
@@ -29,23 +29,36 @@ extern "C" {
 
 #include <libimobiledevice/libimobiledevice.h>
 
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
 #define NP_E_SUCCESS                0
 #define NP_E_INVALID_ARG           -1
 #define NP_E_PLIST_ERROR           -2
 #define NP_E_CONN_FAILED           -3
 
 #define NP_E_UNKNOWN_ERROR       -256
+/*@}*/
 
+/** Represents an error code. */
 typedef int16_t np_error_t;
 
-/* Notification IDs for use with post_notification (client --> device) */
+/**
+ * @name Notifications that can be send
+ *
+ * For use with np_post_notification() (client --> device)
+ */
 #define NP_SYNC_WILL_START           "com.apple.itunes-mobdev.syncWillStart"
 #define NP_SYNC_DID_START            "com.apple.itunes-mobdev.syncDidStart"
 #define NP_SYNC_DID_FINISH           "com.apple.itunes-mobdev.syncDidFinish"
 #define NP_SYNC_LOCK_REQUEST         "com.apple.itunes-mobdev.syncLockRequest"
+/*@}*/
 
-/* Notification IDs for use with observe_notification (device --> client) */
+/**
+ * @name Notifications that can be received
+ *
+ * For use with np_observe_notification() (device --> client)
+ */
+/*@{*/
 #define NP_SYNC_CANCEL_REQUEST       "com.apple.itunes-client.syncCancelRequest"
 #define NP_SYNC_SUSPEND_REQUEST      "com.apple.itunes-client.syncSuspendRequest"
 #define NP_SYNC_RESUME_REQUEST       "com.apple.itunes-client.syncResumeRequest"
@@ -67,6 +80,7 @@ typedef int16_t np_error_t;
 #define NP_ITDBPREP_DID_END          "com.apple.itdbprep.notification.didEnd"
 #define NP_LANGUAGE_CHANGED          "com.apple.language.changed"
 #define NP_ADDRESS_BOOK_PREF_CHANGED "com.apple.AddressBook.PreferenceChanged"
+/*@}*/
 
 typedef struct np_client_private np_client_private;
 typedef np_client_private *np_client_t; /**< The client handle. */
diff --git a/include/libimobiledevice/sbservices.h b/include/libimobiledevice/sbservices.h
index 0fcec86..71e951e 100644
--- a/include/libimobiledevice/sbservices.h
+++ b/include/libimobiledevice/sbservices.h
@@ -29,14 +29,17 @@ extern "C" {
 
 #include <libimobiledevice/libimobiledevice.h>
 
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
 #define SBSERVICES_E_SUCCESS                0
 #define SBSERVICES_E_INVALID_ARG           -1
 #define SBSERVICES_E_PLIST_ERROR           -2
 #define SBSERVICES_E_CONN_FAILED           -3
 
 #define SBSERVICES_E_UNKNOWN_ERROR       -256
+/*@}*/
 
+/** Represents an error code. */
 typedef int16_t sbservices_error_t;
 
 typedef struct sbservices_client_private sbservices_client_private;
diff --git a/include/libimobiledevice/screenshotr.h b/include/libimobiledevice/screenshotr.h
index d9a3ffd..7e5c8a7 100644
--- a/include/libimobiledevice/screenshotr.h
+++ b/include/libimobiledevice/screenshotr.h
@@ -29,7 +29,8 @@ extern "C" {
 
 #include <libimobiledevice/libimobiledevice.h>
 
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
 #define SCREENSHOTR_E_SUCCESS                0
 #define SCREENSHOTR_E_INVALID_ARG           -1
 #define SCREENSHOTR_E_PLIST_ERROR           -2
@@ -37,7 +38,9 @@ extern "C" {
 #define SCREENSHOTR_E_BAD_VERSION           -4
 
 #define SCREENSHOTR_E_UNKNOWN_ERROR       -256
+/*@}*/
 
+/** Represents an error code. */
 typedef int16_t screenshotr_error_t;
 
 typedef struct screenshotr_client_private screenshotr_client_private;
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
  *