Moved Doxygen comments from source files to public headers.

Conflicts:
	include/libimobiledevice/afc.h

1 files changed, 147 insertions, 0 deletions

diff --git a/include/libimobiledevice/libimobiledevice.h b/include/libimobiledevice/libimobiledevice.h
index e33715f..3cbb96b 100644
--- a/include/libimobiledevice/libimobiledevice.h
+++ b/include/libimobiledevice/libimobiledevice.h
@@ -75,30 +75,177 @@ typedef struct {
 typedef void (*idevice_event_cb_t) (const idevice_event_t *event, void *user_data);
 
 /* functions */
+
+/**
+ * Register a callback function that will be called when device add/remove
+ * events occur.
+ *
+ * @param callback Callback function to call.
+ * @param user_data Application-specific data passed as parameter
+ *   to the registered callback function.
+ *
+ * @return IDEVICE_E_SUCCESS on success or an error value when an error occured.
+ */
 idevice_error_t idevice_event_subscribe(idevice_event_cb_t callback, void *user_data);
+
+/**
+ * Release the event callback function that has been registered with
+ *  idevice_event_subscribe().
+ *
+ * @return IDEVICE_E_SUCCESS on success or an error value when an error occured.
+ */
 idevice_error_t idevice_event_unsubscribe();
 
 /* discovery (synchronous) */
+
+/**
+ * Get a list of currently available devices.
+ *
+ * @param devices List of udids of devices that are currently available.
+ *   This list is terminated by a NULL pointer.
+ * @param count Number of devices found.
+ *
+ * @return IDEVICE_E_SUCCESS on success or an error value when an error occured.
+ */
 idevice_error_t idevice_get_device_list(char ***devices, int *count);
+
+/**
+ * Free a list of device udids.
+ *
+ * @param devices List of udids to free.
+ *
+ * @return Always returnes IDEVICE_E_SUCCESS.
+ */
 idevice_error_t idevice_device_list_free(char **devices);
 
 /* device structure creation and destruction */
+        
+/**
+ * Creates an idevice_t structure for the device specified by udid,
+ *  if the device is available.
+ *
+ * @note The resulting idevice_t structure has to be freed with
+ * idevice_free() if it is no longer used.
+ *
+ * @param device Upon calling this function, a pointer to a location of type
+ *  idevice_t. On successful return, this location will be populated.
+ * @param udid The UDID to match.
+ *
+ * @return IDEVICE_E_SUCCESS if ok, otherwise an error code.
+ */
 idevice_error_t idevice_new(idevice_t *device, const char *udid);
+
+/**
+ * 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.
+ *
+ * @param device idevice_t to free.
+ */
 idevice_error_t idevice_free(idevice_t device);
 
 /* connection/disconnection */
+        
+/**
+ * Set up a connection to the given device.
+ *
+ * @param device The device to connect to.
+ * @param port The destination port to connect to.
+ * @param connection Pointer to an idevice_connection_t that will be filled
+ *   with the necessary data of the connection.
+ *
+ * @return IDEVICE_E_SUCCESS if ok, otherwise an error code.
+ */
 idevice_error_t idevice_connect(idevice_t device, uint16_t port, idevice_connection_t *connection);
+
+/**
+ * Disconnect from the device and clean up the connection structure.
+ *
+ * @param connection The connection to close.
+ *
+ * @return IDEVICE_E_SUCCESS if ok, otherwise an error code.
+ */
 idevice_error_t idevice_disconnect(idevice_connection_t connection);
 
 /* communication */
+        
+/**
+ * Send data to a device via the given connection.
+ *
+ * @param connection The connection to send data over.
+ * @param data Buffer with data to send.
+ * @param len Size of the buffer to send.
+ * @param sent_bytes Pointer to an uint32_t that will be filled
+ *   with the number of bytes actually sent.
+ *
+ * @return IDEVICE_E_SUCCESS if ok, otherwise an error code.
+ */
 idevice_error_t idevice_connection_send(idevice_connection_t connection, const char *data, uint32_t len, uint32_t *sent_bytes);
+
+/**
+ * Receive data from a device via the given connection.
+ * This function will return after the given timeout even if no data has been
+ * received.
+ *
+ * @param connection The connection to receive data from.
+ * @param data Buffer that will be filled with the received data.
+ *   This buffer has to be large enough to hold len bytes.
+ * @param len Buffer size or number of bytes to receive.
+ * @param recv_bytes Number of bytes actually received.
+ * @param timeout Timeout in milliseconds after which this function should
+ *   return even if no data has been received.
+ *
+ * @return IDEVICE_E_SUCCESS if ok, otherwise an error code.
+ */
 idevice_error_t idevice_connection_receive_timeout(idevice_connection_t connection, char *data, uint32_t len, uint32_t *recv_bytes, unsigned int timeout);
+        
+/**
+ * Receive data from a device via the given connection.
+ * This function is like idevice_connection_receive_timeout, but with a
+ * predefined reasonable timeout.
+ *
+ * @param connection The connection to receive data from.
+ * @param data Buffer that will be filled with the received data.
+ *   This buffer has to be large enough to hold len bytes.
+ * @param len Buffer size or number of bytes to receive.
+ * @param recv_bytes Number of bytes actually received.
+ *
+ * @return IDEVICE_E_SUCCESS if ok, otherwise an error code.
+ */
 idevice_error_t idevice_connection_receive(idevice_connection_t connection, char *data, uint32_t len, uint32_t *recv_bytes);
+        
+/**
+ * Enables SSL for the given connection.
+ *
+ * @param connection The connection to enable SSL for.
+ *
+ * @return IDEVICE_E_SUCCESS on success, IDEVICE_E_INVALID_ARG when connection
+ *     is NULL or connection->ssl_data is non-NULL, or IDEVICE_E_SSL_ERROR when
+ *     SSL initialization, setup, or handshake fails.
+ */
 idevice_error_t idevice_connection_enable_ssl(idevice_connection_t connection);
+        
+/**
+ * Disable SSL for the given connection.
+ *
+ * @param connection The connection to disable SSL for.
+ *
+ * @return IDEVICE_E_SUCCESS on success, IDEVICE_E_INVALID_ARG when connection
+ *     is NULL. This function also returns IDEVICE_E_SUCCESS when SSL is not
+ *     enabled and does no further error checking on cleanup.
+ */
 idevice_error_t idevice_connection_disable_ssl(idevice_connection_t connection);
 
 /* misc */
+        
+/**
+ * Gets the handle of the device. Depends on the connection type.
+ */
 idevice_error_t idevice_get_handle(idevice_t device, uint32_t *handle);
+        
+/**
+ * Gets the unique id for the device.
+ */
 idevice_error_t idevice_get_udid(idevice_t device, char **udid);
 
 #ifdef __cplusplus