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.

1 files changed, 120 insertions, 93 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);