Documentation fixes

26 files changed, 177 insertions, 86 deletions

diff --git a/include/libimobiledevice/afc.h b/include/libimobiledevice/afc.h
index b59b070..a2d70d3 100644
--- a/include/libimobiledevice/afc.h
+++ b/include/libimobiledevice/afc.h
@@ -31,6 +31,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the AFC service */
 #define AFC_SERVICE_NAME "com.apple.afc"
 
 /** Error Codes */
@@ -89,7 +90,7 @@ typedef enum {
         AFC_LOCK_UN = 8 | 4  /**< unlock */
 } afc_lock_op_t;
 
-typedef struct afc_client_private afc_client_private;
+typedef struct afc_client_private afc_client_private; /**< \private */
 typedef afc_client_private *afc_client_t; /**< The client handle. */
 
 /* Interface */
diff --git a/include/libimobiledevice/companion_proxy.h b/include/libimobiledevice/companion_proxy.h
index 19c88eb..d786766 100644
--- a/include/libimobiledevice/companion_proxy.h
+++ b/include/libimobiledevice/companion_proxy.h
@@ -30,6 +30,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the companion proxy service */
 #define COMPANION_PROXY_SERVICE_NAME "com.apple.companion_proxy"
 
 /** Error Codes */
@@ -48,9 +49,10 @@ typedef enum {
         COMPANION_PROXY_E_UNKNOWN_ERROR   = -256
 } companion_proxy_error_t;
 
-typedef struct companion_proxy_client_private companion_proxy_client_private;
+typedef struct companion_proxy_client_private companion_proxy_client_private; /**< \private */
 typedef companion_proxy_client_private *companion_proxy_client_t; /**< The client handle. */
 
+/** Callback for companion device events */
 typedef void (*companion_proxy_device_event_cb_t) (plist_t event, void* userdata);
 
 /**
@@ -119,7 +121,7 @@ companion_proxy_error_t companion_proxy_receive(companion_proxy_client_t client,
  * Retrieves a list of paired devices.
  *
  * @param client The companion_proxy client
- * @param devices Point that will receive a PLIST_ARRAY with paired device UDIDs
+ * @param paired_devices Point that will receive a PLIST_ARRAY with paired device UDIDs
  *
  * @note The device closes the connection after sending the reply.
  *
@@ -161,6 +163,8 @@ companion_proxy_error_t companion_proxy_stop_listening_for_devices(companion_pro
  * @param client The companion_proxy client
  * @param companion_udid UDID of the (paired) companion device
  * @param key The key to retrieve the value for
+ * @param value A pointer to a plist_t that will receive the value for the given key.
+ *   The consumer is responsible for freeing the value with plist_free() when no longer needed.
  *
  * @note The device closes the connection after sending the reply.
  *
diff --git a/include/libimobiledevice/debugserver.h b/include/libimobiledevice/debugserver.h
index 90ba514..eaa7c48 100644
--- a/include/libimobiledevice/debugserver.h
+++ b/include/libimobiledevice/debugserver.h
@@ -30,7 +30,9 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the debugserver service */
 #define DEBUGSERVER_SERVICE_NAME "com.apple.debugserver"
+/** Service identifier passed to lockdownd_start_service() to start the secure debugserver service */
 #define DEBUGSERVER_SECURE_SERVICE_NAME DEBUGSERVER_SERVICE_NAME ".DVTSecureSocketProxy"
 
 /** Error Codes */
@@ -44,10 +46,10 @@ typedef enum {
         DEBUGSERVER_E_UNKNOWN_ERROR  = -256
 } debugserver_error_t;
 
-typedef struct debugserver_client_private debugserver_client_private;
+typedef struct debugserver_client_private debugserver_client_private; /**< \private */
 typedef debugserver_client_private *debugserver_client_t; /**< The client handle. */
 
-typedef struct debugserver_command_private debugserver_command_private;
+typedef struct debugserver_command_private debugserver_command_private; /**< \private */
 typedef debugserver_command_private *debugserver_command_t; /**< The command handle. */
 
 /* Interface */
diff --git a/include/libimobiledevice/diagnostics_relay.h b/include/libimobiledevice/diagnostics_relay.h
index d37ad74..f80a86b 100644
--- a/include/libimobiledevice/diagnostics_relay.h
+++ b/include/libimobiledevice/diagnostics_relay.h
@@ -30,6 +30,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the diagnostics relay service */
 #define DIAGNOSTICS_RELAY_SERVICE_NAME "com.apple.mobile.diagnostics_relay"
 
 /** Error Codes */
@@ -42,18 +43,19 @@ typedef enum {
         DIAGNOSTICS_RELAY_E_UNKNOWN_ERROR   = -256
 } diagnostics_relay_error_t;
 
+/** Action type for #diagnostics_relay_restart and #diagnostics_relay_shutdown */
 typedef enum {
     DIAGNOSTICS_RELAY_ACTION_FLAG_WAIT_FOR_DISCONNECT = 1 << 1,
     DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_PASS = 1 << 2,
     DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_FAIL = 1 << 3
 } diagnostics_relay_action_t;
 
-#define DIAGNOSTICS_RELAY_REQUEST_TYPE_ALL                "All"
-#define DIAGNOSTICS_RELAY_REQUEST_TYPE_WIFI               "WiFi"
-#define DIAGNOSTICS_RELAY_REQUEST_TYPE_GAS_GAUGE          "GasGauge"
-#define DIAGNOSTICS_RELAY_REQUEST_TYPE_NAND               "NAND"
+#define DIAGNOSTICS_RELAY_REQUEST_TYPE_ALL                "All"      /**< Query all available diagnostics */
+#define DIAGNOSTICS_RELAY_REQUEST_TYPE_WIFI               "WiFi"     /**< Query WiFi diagnostics */
+#define DIAGNOSTICS_RELAY_REQUEST_TYPE_GAS_GAUGE          "GasGauge" /**< Query GasGauge diagnostics */
+#define DIAGNOSTICS_RELAY_REQUEST_TYPE_NAND               "NAND"     /**< Query NAND diagnostics */
 
-typedef struct diagnostics_relay_client_private diagnostics_relay_client_private;
+typedef struct diagnostics_relay_client_private diagnostics_relay_client_private; /**< \private */
 typedef diagnostics_relay_client_private *diagnostics_relay_client_t; /**< The client handle. */
 
 /**
@@ -158,14 +160,13 @@ diagnostics_relay_error_t diagnostics_relay_restart(diagnostics_relay_client_t c
 diagnostics_relay_error_t diagnostics_relay_shutdown(diagnostics_relay_client_t client, diagnostics_relay_action_t flags);
 
 /**
- * Shutdown of the device and optionally show a user notification.
+ * Request diagnostics information for a given type.
  *
  * @param client The diagnostics_relay client
- * @param flags A binary flag combination of
- *        DIAGNOSTICS_RELAY_ACTION_FLAG_WAIT_FOR_DISCONNECT to wait until
- *        diagnostics_relay_client_free() disconnects before execution and
- *        DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_FAIL to show a "FAIL" dialog
- *        or DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_PASS to show an "OK" dialog
+ * @param type The type or domain to query for diagnostics. Some known values
+ *     are "All", "WiFi", "GasGauge", and "NAND".
+ * @param diagnostics A pointer to plist_t that will receive the diagnostics information.
+ *     The consumer has to free the allocated memory with plist_free() when no longer needed.
  *
  * @return DIAGNOSTICS_RELAY_E_SUCCESS on success,
  *  DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL,
@@ -174,10 +175,50 @@ diagnostics_relay_error_t diagnostics_relay_shutdown(diagnostics_relay_client_t
  */
 diagnostics_relay_error_t diagnostics_relay_request_diagnostics(diagnostics_relay_client_t client, const char* type, plist_t* diagnostics);
 
+/**
+ * Query one or multiple MobileGestalt keys.
+ *
+ * @param client The diagnostics_relay client
+ * @param keys A PLIST_ARRAY with the keys to query.
+ * @param result A pointer to plist_t that will receive the result. The consumer
+ *     has to free the allocated memory with plist_free() when no longer needed.
+ *
+ * @return DIAGNOSTICS_RELAY_E_SUCCESS on success,
+ *  DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL,
+ *  DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the
+ *  request
+ */
 diagnostics_relay_error_t diagnostics_relay_query_mobilegestalt(diagnostics_relay_client_t client, plist_t keys, plist_t* result);
 
+/**
+ * Query an IORegistry entry of a given class.
+ *
+ * @param client The diagnostics_relay client
+ * @param entry_name The IORegistry entry name to query.
+ * @param entry_class The IORegistry class to query.
+ * @param result A pointer to plist_t that will receive the result. The consumer
+ *     has to free the allocated memory with plist_free() when no longer needed.
+ *
+ * @return DIAGNOSTICS_RELAY_E_SUCCESS on success,
+ *  DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL,
+ *  DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the
+ *  request
+ */
 diagnostics_relay_error_t diagnostics_relay_query_ioregistry_entry(diagnostics_relay_client_t client, const char* entry_name, const char* entry_class, plist_t* result);
 
+/**
+ * Query an IORegistry plane.
+ *
+ * @param client The diagnostics_relay client
+ * @param plane The IORegistry plane name to query.
+ * @param result A pointer to plist_t that will receive the result. The consumer
+ *     has to free the allocated memory with plist_free() when no longer needed.
+ *
+ * @return DIAGNOSTICS_RELAY_E_SUCCESS on success,
+ *  DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL,
+ *  DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the
+ *  request
+ */
 diagnostics_relay_error_t diagnostics_relay_query_ioregistry_plane(diagnostics_relay_client_t client, const char* plane, plist_t* result);
 
 #ifdef __cplusplus
diff --git a/include/libimobiledevice/file_relay.h b/include/libimobiledevice/file_relay.h
index e41bb2d..6b30e65 100644
--- a/include/libimobiledevice/file_relay.h
+++ b/include/libimobiledevice/file_relay.h
@@ -32,6 +32,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the file relay service */
 #define FILE_RELAY_SERVICE_NAME "com.apple.mobile.file_relay"
 
 /** Error Codes */
@@ -46,7 +47,7 @@ typedef enum {
         FILE_RELAY_E_UNKNOWN_ERROR     = -256
 } file_relay_error_t;
 
-typedef struct file_relay_client_private file_relay_client_private;
+typedef struct file_relay_client_private file_relay_client_private; /**< \private */
 typedef file_relay_client_private *file_relay_client_t; /**< The client handle. */
 
 /**
@@ -110,8 +111,7 @@ file_relay_error_t file_relay_client_free(file_relay_client_t client);
  *     data using idevice_connection_receive(). The connection will be closed
  *     automatically by the device, but use file_relay_client_free() to clean
  *     up properly.
- * @param timeout Maximum time in milliseconds to wait for data.
- *
+  *
  * @note WARNING: Don't call this function without reading the data afterwards.
  *     A directory mobile_file_relay.XXXX used for creating the archive will
  *     remain in the /tmp directory otherwise.
@@ -144,6 +144,7 @@ file_relay_error_t file_relay_request_sources(file_relay_client_t client, const
  *     data using idevice_connection_receive(). The connection will be closed
  *     automatically by the device, but use file_relay_client_free() to clean
  *     up properly.
+ * @param timeout Maximum time in milliseconds to wait for data.
  *
  * @note WARNING: Don't call this function without reading the data afterwards.
  *     A directory mobile_file_relay.XXXX used for creating the archive will
diff --git a/include/libimobiledevice/heartbeat.h b/include/libimobiledevice/heartbeat.h
index 1f5344a..42b318d 100644
--- a/include/libimobiledevice/heartbeat.h
+++ b/include/libimobiledevice/heartbeat.h
@@ -30,6 +30,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the heartbeat service */
 #define HEARTBEAT_SERVICE_NAME "com.apple.mobile.heartbeat"
 
 /** Error Codes */
@@ -44,7 +45,7 @@ typedef enum {
         HEARTBEAT_E_UNKNOWN_ERROR   = -256
 } heartbeat_error_t;
 
-typedef struct heartbeat_client_private heartbeat_client_private;
+typedef struct heartbeat_client_private heartbeat_client_private; /**< \private */
 typedef heartbeat_client_private *heartbeat_client_t; /**< The client handle. */
 
 /**
@@ -116,7 +117,7 @@ heartbeat_error_t heartbeat_receive(heartbeat_client_t client, plist_t * plist);
  * @param client The heartbeat client to use for receiving
  * @param plist pointer to a plist_t that will point to the received plist
  *      upon successful return
- * @param timeout Maximum time in milliseconds to wait for data.
+ * @param timeout_ms Maximum time in milliseconds to wait for data.
  *
  * @return HEARTBEAT_E_SUCCESS on success,
  *      HEARTBEAT_E_INVALID_ARG when client or *plist is NULL,
diff --git a/include/libimobiledevice/house_arrest.h b/include/libimobiledevice/house_arrest.h
index 5a42838..3785847 100644
--- a/include/libimobiledevice/house_arrest.h
+++ b/include/libimobiledevice/house_arrest.h
@@ -32,6 +32,7 @@ extern "C" {
 #include <libimobiledevice/lockdown.h>
 #include <libimobiledevice/afc.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the house arrest service */
 #define HOUSE_ARREST_SERVICE_NAME "com.apple.mobile.house_arrest"
 
 /** Error Codes */
@@ -44,7 +45,7 @@ typedef enum {
         HOUSE_ARREST_E_UNKNOWN_ERROR = -256
 } house_arrest_error_t;
 
-typedef struct house_arrest_client_private house_arrest_client_private;
+typedef struct house_arrest_client_private house_arrest_client_private; /**< \private */
 typedef house_arrest_client_private *house_arrest_client_t; /**< The client handle. */
 
 /* Interface */
diff --git a/include/libimobiledevice/installation_proxy.h b/include/libimobiledevice/installation_proxy.h
index e96e224..87132b9 100644
--- a/include/libimobiledevice/installation_proxy.h
+++ b/include/libimobiledevice/installation_proxy.h
@@ -33,6 +33,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the installation proxy service */
 #define INSTPROXY_SERVICE_NAME "com.apple.mobile.installation_proxy"
 
 /** Error Codes */
@@ -107,7 +108,7 @@ typedef enum {
         INSTPROXY_E_UNKNOWN_ERROR                                             = -256
 } instproxy_error_t;
 
-typedef struct instproxy_client_private instproxy_client_private;
+typedef struct instproxy_client_private instproxy_client_private; /**< \private */
 typedef instproxy_client_private *instproxy_client_t; /**< The client handle. */
 
 /** Reports the status response of the given command */
@@ -441,8 +442,8 @@ void instproxy_status_get_current_list(plist_t status, uint64_t* total, uint64_t
  * Gets progress in percentage from a status if available.
  *
  * @param status The dictionary status response to use.
- * @param name Pointer to store the progress in percent (0-100) or -1 if not
- *        progress was found in the status.
+ * @param percent Pointer to an int to store the progress in percent (0-100)
+ *        or -1 if no progress was found in the status.
  */
 void instproxy_status_get_percent_complete(plist_t status, int *percent);
 
@@ -487,7 +488,7 @@ void instproxy_client_options_free(plist_t client_options);
  * Queries the device for the path of an application.
  *
  * @param client The connected installation proxy client.
- * @param appid ApplicationIdentifier of app to retrieve the path for.
+ * @param bundle_id ApplicationIdentifier of app to retrieve the path for.
  * @param path Pointer to store the device path for the application
  *        which is set to NULL if it could not be determined.
  *
diff --git a/include/libimobiledevice/libimobiledevice.h b/include/libimobiledevice/libimobiledevice.h
index 40edd71..c3b87cd 100644
--- a/include/libimobiledevice/libimobiledevice.h
+++ b/include/libimobiledevice/libimobiledevice.h
@@ -47,10 +47,10 @@ typedef enum {
         IDEVICE_E_TIMEOUT         = -7
 } idevice_error_t;
 
-typedef struct idevice_private idevice_private;
+typedef struct idevice_private idevice_private; /**< \private */
 typedef idevice_private *idevice_t; /**< The device handle. */
 
-typedef struct idevice_connection_private idevice_connection_private;
+typedef struct idevice_connection_private idevice_connection_private; /**< \private */
 typedef idevice_connection_private *idevice_connection_t; /**< The connection handle. */
 
 /** Options for idevice_new_with_options() */
@@ -62,23 +62,24 @@ enum idevice_options {
 
 /** Type of connection a device is available on */
 enum idevice_connection_type {
-        CONNECTION_USBMUXD = 1,
-        CONNECTION_NETWORK
+        CONNECTION_USBMUXD = 1, /**< device is available via USBMUX */
+        CONNECTION_NETWORK /**< device is available via network */
 };
 
+/** Device information returned by #idevice_get_device_list_extended API */
 struct idevice_info {
-        char *udid;
-        enum idevice_connection_type conn_type;
-        void* conn_data;
+        char *udid; /**< UDID of the device */
+        enum idevice_connection_type conn_type; /**< Type of connection the device is available on */
+        void* conn_data; /**< Connection data, depending on the connection type */
 };
 typedef struct idevice_info* idevice_info_t;
 
 /* discovery (events/asynchronous) */
 /** The event type for device add or removal */
 enum idevice_event_type {
-        IDEVICE_DEVICE_ADD = 1,
-        IDEVICE_DEVICE_REMOVE,
-        IDEVICE_DEVICE_PAIRED
+        IDEVICE_DEVICE_ADD = 1, /**< device was added */
+        IDEVICE_DEVICE_REMOVE, /**< device was removed */
+        IDEVICE_DEVICE_PAIRED /**< device completed pairing process */
 };
 
 /* event data structure */
@@ -338,12 +339,22 @@ idevice_error_t idevice_connection_get_fd(idevice_connection_t connection, int *
 /* misc */
 
 /**
- * Gets the handle or (usbmux device id) of the device.
+ * Gets the handle or (USBMUX device id) of the device.
+ *
+ * @param device The device to get the USBMUX device id for.
+ * @param handle Pointer to a uint32_t that will be set to the USBMUX handle value.
+ *
+ * @return IDEVICE_E_SUCCESS on success, otherwise an error code.
  */
 idevice_error_t idevice_get_handle(idevice_t device, uint32_t *handle);
 
 /**
- * Gets the unique id for the device.
+ * Gets the Unique Device ID for the device.
+ *
+ * @param device The device to get the Unique Device ID for.
+ * @param udid Pointer that will be set to an allocated buffer with the device UDID. The consumer is responsible for releasing the allocated memory.
+ *
+ * @return IDEVICE_E_SUCCESS on success, otherwise an error code.
  */
 idevice_error_t idevice_get_udid(idevice_t device, char **udid);
 
diff --git a/include/libimobiledevice/lockdown.h b/include/libimobiledevice/lockdown.h
index 1569f44..f22917a 100644
--- a/include/libimobiledevice/lockdown.h
+++ b/include/libimobiledevice/lockdown.h
@@ -80,7 +80,7 @@ typedef enum {
         LOCKDOWN_E_UNKNOWN_ERROR                           = -256
 } lockdownd_error_t;
 
-typedef struct lockdownd_client_private lockdownd_client_private;
+typedef struct lockdownd_client_private lockdownd_client_private; /**< \private */
 typedef lockdownd_client_private *lockdownd_client_t; /**< The client handle. */
 
 struct lockdownd_pair_record {
@@ -88,19 +88,20 @@ struct lockdownd_pair_record {
         char *host_certificate;   /**< The host certificate */
         char *root_certificate;   /**< The root certificate */
         char *host_id;            /**< A unique HostID for the host computer */
-        char *system_buid;          /**< A unique system id */
+        char *system_buid;        /**< A unique system id */
 };
-/** A pair record holding device, host and root certificates along the host_id */
-typedef struct lockdownd_pair_record *lockdownd_pair_record_t;
+/** pair record holding device, host and root certificates along the host_id */
+typedef struct lockdownd_pair_record *lockdownd_pair_record_t; /**< pair record */
 
+/** service descriptor */
 struct lockdownd_service_descriptor {
-        uint16_t port;
-        uint8_t ssl_enabled;
-        char* identifier;
+        uint16_t port; /**< port number the service was started on */
+        uint8_t ssl_enabled; /**< an indicator if the service requires SSL */
+        char* identifier; /**< identifier of the service */
 };
 typedef struct lockdownd_service_descriptor *lockdownd_service_descriptor_t;
 
-
+/** Callback types used in #lockdownd_cu_pairing_cb_t */
 typedef enum {
         LOCKDOWN_CU_PAIRING_PIN_REQUESTED, /**< PIN requested: data_ptr is a char* buffer, and data_size points to the size of this buffer that must not be exceeded and has to be updated to the actual number of characters filled into the buffer. */
         LOCKDOWN_CU_PAIRING_DEVICE_INFO, /**< device information available: data_ptr is a plist_t, and data_size is ignored. The plist_t has to be copied if required, since it is freed when the callback function returns. */
@@ -564,7 +565,7 @@ lockdownd_error_t lockdownd_service_descriptor_free(lockdownd_service_descriptor
 /**
  * Gets a readable error string for a given lockdown error code.
  *
- * @params err A lockdownd error code
+ * @param err A lockdownd error code
  *
  * @returns A readable error string
  */
diff --git a/include/libimobiledevice/misagent.h b/include/libimobiledevice/misagent.h
index 09af57a..394f5ce 100644
--- a/include/libimobiledevice/misagent.h
+++ b/include/libimobiledevice/misagent.h
@@ -31,6 +31,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the misagent service */
 #define MISAGENT_SERVICE_NAME "com.apple.misagent"
 
 /** Error Codes */
@@ -43,7 +44,7 @@ typedef enum {
         MISAGENT_E_UNKNOWN_ERROR  = -256
 } misagent_error_t;
 
-typedef struct misagent_client_private misagent_client_private;
+typedef struct misagent_client_private misagent_client_private; /**< \private */
 typedef misagent_client_private *misagent_client_t; /**< The client handle. */
 
 /* Interface */
diff --git a/include/libimobiledevice/mobile_image_mounter.h b/include/libimobiledevice/mobile_image_mounter.h
index e185ad5..891df40 100644
--- a/include/libimobiledevice/mobile_image_mounter.h
+++ b/include/libimobiledevice/mobile_image_mounter.h
@@ -31,6 +31,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the mobile image mounter service */
 #define MOBILE_IMAGE_MOUNTER_SERVICE_NAME "com.apple.mobile.mobile_image_mounter"
 
 /** Error Codes */
@@ -44,7 +45,7 @@ typedef enum {
         MOBILE_IMAGE_MOUNTER_E_UNKNOWN_ERROR  = -256
 } mobile_image_mounter_error_t;
 
-typedef struct mobile_image_mounter_client_private mobile_image_mounter_client_private;
+typedef struct mobile_image_mounter_client_private mobile_image_mounter_client_private; /**< \private */
 typedef mobile_image_mounter_client_private *mobile_image_mounter_client_t; /**< The client handle. */
 
 /** callback for image upload */
diff --git a/include/libimobiledevice/mobileactivation.h b/include/libimobiledevice/mobileactivation.h
index 51de205..774c116 100644
--- a/include/libimobiledevice/mobileactivation.h
+++ b/include/libimobiledevice/mobileactivation.h
@@ -30,6 +30,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the mobile activation service */
 #define MOBILEACTIVATION_SERVICE_NAME "com.apple.mobileactivationd"
 
 /** Error Codes */
@@ -43,7 +44,7 @@ typedef enum {
         MOBILEACTIVATION_E_UNKNOWN_ERROR   = -256
 } mobileactivation_error_t;
 
-typedef struct mobileactivation_client_private mobileactivation_client_private;
+typedef struct mobileactivation_client_private mobileactivation_client_private; /**< \private */
 typedef mobileactivation_client_private *mobileactivation_client_t; /**< The client handle. */
 
 /**
@@ -138,7 +139,7 @@ mobileactivation_error_t mobileactivation_create_activation_info(mobileactivatio
  * provided by mobileactivation_create_activation_session_info().
  *
  * @param client The mobileactivation client
- * @aram handshake_response The handshake response returned from drmHandshake
+ * @param handshake_response The handshake response returned from drmHandshake
  * @param info Pointer to a plist_t variable that will be set to the
  *     activation info created by the mobileactivation service. The
  *     consumer is responsible for freeing the returned object using
diff --git a/include/libimobiledevice/mobilebackup.h b/include/libimobiledevice/mobilebackup.h
index f22150d..d4c042e 100644
--- a/include/libimobiledevice/mobilebackup.h
+++ b/include/libimobiledevice/mobilebackup.h
@@ -31,6 +31,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the mobilebackup service */
 #define MOBILEBACKUP_SERVICE_NAME "com.apple.mobilebackup"
 
 /** Error Codes */
@@ -46,9 +47,10 @@ typedef enum {
         MOBILEBACKUP_E_UNKNOWN_ERROR   = -256
 } mobilebackup_error_t;
 
-typedef struct mobilebackup_client_private mobilebackup_client_private;
+typedef struct mobilebackup_client_private mobilebackup_client_private; /**< \private */
 typedef mobilebackup_client_private *mobilebackup_client_t; /**< The client handle. */
 
+/** Available flags passed to #mobilebackup_request_restore */
 typedef enum {
         MB_RESTORE_NOTIFY_SPRINGBOARD = 1 << 0,
         MB_RESTORE_PRESERVE_SETTINGS = 1 << 1,
diff --git a/include/libimobiledevice/mobilebackup2.h b/include/libimobiledevice/mobilebackup2.h
index 239c807..1af4141 100644
--- a/include/libimobiledevice/mobilebackup2.h
+++ b/include/libimobiledevice/mobilebackup2.h
@@ -31,6 +31,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the mobilebackup2 service */
 #define MOBILEBACKUP2_SERVICE_NAME "com.apple.mobilebackup2"
 
 /** Error Codes */
@@ -47,7 +48,7 @@ typedef enum {
         MOBILEBACKUP2_E_UNKNOWN_ERROR     = -256
 } mobilebackup2_error_t;
 
-typedef struct mobilebackup2_client_private mobilebackup2_client_private;
+typedef struct mobilebackup2_client_private mobilebackup2_client_private; /**< \private */
 typedef mobilebackup2_client_private *mobilebackup2_client_t; /**< The client handle. */
 
 
@@ -156,7 +157,7 @@ mobilebackup2_error_t mobilebackup2_send_raw(mobilebackup2_client_t client, cons
  * @param data Pointer to a buffer that will be filled with the received data.
  * @param length Number of bytes to receive. The data buffer needs to be large
  *     enough to store this amount of data.
- * @paran bytes Number of bytes actually received.
+ * @param bytes Number of bytes actually received.
  *
  * @return MOBILEBACKUP2_E_SUCCESS if any or no data was received,
  *     MOBILEBACKUP2_E_INVALID_ARG if one of the parameters is invalid,
diff --git a/include/libimobiledevice/mobilesync.h b/include/libimobiledevice/mobilesync.h
index 005ef3f..6b1af18 100644
--- a/include/libimobiledevice/mobilesync.h
+++ b/include/libimobiledevice/mobilesync.h
@@ -34,6 +34,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the mobilesync service */
 #define MOBILESYNC_SERVICE_NAME "com.apple.mobilesync"
 
 /** Error Codes */
@@ -59,14 +60,16 @@ typedef enum {
         MOBILESYNC_SYNC_TYPE_RESET /**< Reset-sync signals that the computer should send all data again. */
 } mobilesync_sync_type_t;
 
-typedef struct mobilesync_client_private mobilesync_client_private;
+typedef struct mobilesync_client_private mobilesync_client_private; /**< \private */
 typedef mobilesync_client_private *mobilesync_client_t; /**< The client handle */
 
+/** Anchors used by the device and computer (structure) */
 typedef struct {
-        char *device_anchor;
-        char *computer_anchor;
+        char *device_anchor; /**< device anchor */
+        char *computer_anchor; /**< computer anchor */
 } mobilesync_anchors;
-typedef mobilesync_anchors *mobilesync_anchors_t; /**< Anchors used by the device and computer. */
+/** Anchors used by the device and computer */
+typedef mobilesync_anchors *mobilesync_anchors_t;
 
 /* Interface */
 
diff --git a/include/libimobiledevice/notification_proxy.h b/include/libimobiledevice/notification_proxy.h
index a9d2d3f..872692c 100644
--- a/include/libimobiledevice/notification_proxy.h
+++ b/include/libimobiledevice/notification_proxy.h
@@ -31,6 +31,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the notification proxy service */
 #define NP_SERVICE_NAME "com.apple.mobile.notification_proxy"
 
 /** Error Codes */
@@ -43,22 +44,26 @@ typedef enum {
 } np_error_t;
 
 /**
- * @name Notifications that can be send
+ * @name Notifications that can be sent
  *
  * For use with np_post_notification() (client --> device)
  */
+/**@{*/
+//! @cond
 #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"
-/*@}*/
+//! @endcond
+/**@}*/
 
 /**
  * @name Notifications that can be received
  *
  * For use with np_observe_notification() (device --> client)
  */
-/*@{*/
+/**@{*/
+//! @cond
 #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"
@@ -81,12 +86,13 @@ typedef enum {
 #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"
-/*@}*/
+//! @endcond
+/**@}*/
 
-typedef struct np_client_private np_client_private;
+typedef struct np_client_private np_client_private; /**< \private */
 typedef np_client_private *np_client_t; /**< The client handle. */
 
-/** Reports which notification was received. */
+/** Callback function that reports which notification was received. */
 typedef void (*np_notify_cb_t) (const char *notification, void *user_data);
 
 /* Interface */
@@ -177,7 +183,7 @@ np_error_t np_observe_notifications(np_client_t client, const char **notificatio
  * @param client the NP client
  * @param notify_cb pointer to a callback function or NULL to de-register a
  *        previously set callback function.
- * @param user_data Pointer that will be passed to the callback function as
+ * @param userdata Pointer that will be passed to the callback function as
  *        user data. If notify_cb is NULL, this parameter is ignored.
  *
  * @note Only one callback function can be registered at the same time;
diff --git a/include/libimobiledevice/preboard.h b/include/libimobiledevice/preboard.h
index 60b8e26..88e9806 100644
--- a/include/libimobiledevice/preboard.h
+++ b/include/libimobiledevice/preboard.h
@@ -30,6 +30,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the preboard service */
 #define PREBOARD_SERVICE_NAME "com.apple.preboardservice_v2"
 
 /** Error Codes */
@@ -45,7 +46,7 @@ typedef enum {
         PREBOARD_E_UNKNOWN_ERROR   = -256
 } preboard_error_t;
 
-typedef struct preboard_client_private preboard_client_private;
+typedef struct preboard_client_private preboard_client_private; /**< \private */
 typedef preboard_client_private *preboard_client_t; /**< The client handle. */
 
 /** Reports the status response of the given command */
@@ -121,6 +122,7 @@ preboard_error_t preboard_receive(preboard_client_t client, plist_t * plist);
  *
  * @param client The preboard client
  * @param plist Pointer to a plist_t what will be set to the received plist
+ * @param timeout_ms Timeout in milliseconds
  *
  * @return PREBOARD_E_SUCCESS on success,
  *  PREBOARD_E_INVALID_ARG when client or plist is NULL,
@@ -148,7 +150,7 @@ preboard_error_t preboard_receive_with_timeout(preboard_client_t client, plist_t
  *     { Timeout: true }
  *     followed by { HideDialog: true }
  * If the user aborts the passcode entry, the device sends a dictionary:
- *     { Error: 1, ErrorString: <error string> }
+ *     { Error: 1, ErrorString: \<error string\> }
  *     followed by { HideDialog: true }
  *
  * @return PREBOARD_E_SUCCESS if the command was successfully submitted,
@@ -170,7 +172,7 @@ preboard_error_t preboard_create_stashbag(preboard_client_t client, plist_t mani
  * receive a dictionary with:
  *     { StashbagCommitComplete: true }
  * or in case of an error:
- *     { StashbagCommitComplete: 0, Error: 1, <optional> ErrorString: <error string> }
+ *     { StashbagCommitComplete: 0, Error: 1, \<optional\> ErrorString: \<error string\> }
  *
  * @return PREBOARD_E_SUCCESS if the command was successfully submitted,
  *  PREBOARD_E_INVALID_ARG when client is invalid,
diff --git a/include/libimobiledevice/property_list_service.h b/include/libimobiledevice/property_list_service.h
index 031d6f8..5205551 100644
--- a/include/libimobiledevice/property_list_service.h
+++ b/include/libimobiledevice/property_list_service.h
@@ -30,7 +30,7 @@ extern "C" {
 
 #include <libimobiledevice/lockdown.h>
 
-/* Error Codes */
+/** Error Codes */
 typedef enum {
         PROPERTY_LIST_SERVICE_E_SUCCESS         =  0,
         PROPERTY_LIST_SERVICE_E_INVALID_ARG     = -1,
@@ -42,7 +42,7 @@ typedef enum {
         PROPERTY_LIST_SERVICE_E_UNKNOWN_ERROR   = -256
 } property_list_service_error_t;
 
-typedef struct property_list_service_client_private property_list_service_private;
+typedef struct property_list_service_client_private property_list_service_private; /**< \private */
 typedef property_list_service_private* property_list_service_client_t; /**< The client handle. */
 
 /* Interface */
diff --git a/include/libimobiledevice/restore.h b/include/libimobiledevice/restore.h
index 950f8fd..0017cfd 100644
--- a/include/libimobiledevice/restore.h
+++ b/include/libimobiledevice/restore.h
@@ -42,7 +42,7 @@ typedef enum {
         RESTORE_E_UNKNOWN_ERROR        = -256
 } restored_error_t;
 
-typedef struct restored_client_private restored_client_private;
+typedef struct restored_client_private restored_client_private; /**< \private */
 typedef restored_client_private *restored_client_t; /**< The client handle. */
 
 /* Interface */
diff --git a/include/libimobiledevice/reverse_proxy.h b/include/libimobiledevice/reverse_proxy.h
index 2539bd9..b7a93ff 100644
--- a/include/libimobiledevice/reverse_proxy.h
+++ b/include/libimobiledevice/reverse_proxy.h
@@ -2,6 +2,7 @@
  * @file libimobiledevice/reverse_proxy.h
  * @brief Provide a reverse proxy to allow the device to communicate through,
  *     which is used during firmware restore.
+ * \internal
  *
  * Copyright (c) 2021 Nikias Bassen, All Rights Reserved.
  *
@@ -29,7 +30,7 @@ extern "C" {
 
 #include <libimobiledevice/libimobiledevice.h>
 
-#define REVERSE_PROXY_DEFAULT_PORT 1082
+#define REVERSE_PROXY_DEFAULT_PORT 1082 /**< default port the reverse proxy is listening on */
 
 /** Error Codes */
 typedef enum {
@@ -43,14 +44,16 @@ typedef enum {
         REVERSE_PROXY_E_UNKNOWN_ERROR   = -256
 } reverse_proxy_error_t;
 
-typedef struct reverse_proxy_client_private reverse_proxy_client_private;
+typedef struct reverse_proxy_client_private reverse_proxy_client_private; /**< \private */
 typedef reverse_proxy_client_private *reverse_proxy_client_t; /**< The client handle. */
 
+/** reverse proxy client type */
 typedef enum {
         RP_TYPE_CTRL = 1, /**< control connection */
         RP_TYPE_CONN      /**< proxy connection */
 } reverse_proxy_client_type_t;
 
+/** reverse proxy status for reverse_proxy_status_cb_t callback */
 typedef enum {
         RP_STATUS_READY = 1,    /**< proxy is ready */
         RP_STATUS_TERMINATE,    /**< proxy terminated */
@@ -60,6 +63,7 @@ typedef enum {
         RP_STATUS_DISCONNECTED, /**< connection closed (only RP_TYPE_CONN) */
 } reverse_proxy_status_t;
 
+/** reverse proxy data direction passed to reverse_proxy_data_cb_t callback */
 typedef enum {
         RP_DATA_DIRECTION_OUT = 1, /**< data going out to remote host */
         RP_DATA_DIRECTION_IN       /**< data coming in from remote host */
diff --git a/include/libimobiledevice/sbservices.h b/include/libimobiledevice/sbservices.h
index 0259d97..509d5b9 100644
--- a/include/libimobiledevice/sbservices.h
+++ b/include/libimobiledevice/sbservices.h
@@ -31,6 +31,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the springboardservices service */
 #define SBSERVICES_SERVICE_NAME "com.apple.springboardservices"
 
 /** Error Codes */
@@ -42,8 +43,7 @@ typedef enum {
         SBSERVICES_E_UNKNOWN_ERROR = -256
 } sbservices_error_t;
 
-/** @name Orientation of the user interface on the device */
-/*@{*/
+/** Orientation of the user interface on the device */
 typedef enum {
   SBSERVICES_INTERFACE_ORIENTATION_UNKNOWN                = 0,
   SBSERVICES_INTERFACE_ORIENTATION_PORTRAIT               = 1,
@@ -51,9 +51,8 @@ typedef enum {
   SBSERVICES_INTERFACE_ORIENTATION_LANDSCAPE_RIGHT        = 3,
   SBSERVICES_INTERFACE_ORIENTATION_LANDSCAPE_LEFT         = 4
 } sbservices_interface_orientation_t;
-/*@}*/
 
-typedef struct sbservices_client_private sbservices_client_private;
+typedef struct sbservices_client_private sbservices_client_private; /**< \private */
 typedef sbservices_client_private *sbservices_client_t; /**< The client handle. */
 
 /* Interface */
diff --git a/include/libimobiledevice/screenshotr.h b/include/libimobiledevice/screenshotr.h
index 83ca96b..ecbbdbe 100644
--- a/include/libimobiledevice/screenshotr.h
+++ b/include/libimobiledevice/screenshotr.h
@@ -32,6 +32,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the screenshotr service */
 #define SCREENSHOTR_SERVICE_NAME "com.apple.mobile.screenshotr"
 
 /** Error Codes */
@@ -46,7 +47,7 @@ typedef enum {
         SCREENSHOTR_E_UNKNOWN_ERROR   = -256
 } screenshotr_error_t;
 
-typedef struct screenshotr_client_private screenshotr_client_private;
+typedef struct screenshotr_client_private screenshotr_client_private; /**< \private */
 typedef screenshotr_client_private *screenshotr_client_t; /**< The client handle. */
 
 
diff --git a/include/libimobiledevice/service.h b/include/libimobiledevice/service.h
index 13d0e15..6842054 100644
--- a/include/libimobiledevice/service.h
+++ b/include/libimobiledevice/service.h
@@ -42,9 +42,10 @@ typedef enum {
         SERVICE_E_UNKNOWN_ERROR       = -256
 } service_error_t;
 
-typedef struct service_client_private service_client_private;
+typedef struct service_client_private service_client_private; /**< \private */
 typedef service_client_private* service_client_t; /**< The client handle. */
 
+/** service constructor cast */
 #define SERVICE_CONSTRUCTOR(x) (int32_t (*)(idevice_t, lockdownd_service_descriptor_t, void**))(x)
 
 /* Interface */
@@ -74,6 +75,8 @@ service_error_t service_client_new(idevice_t device, lockdownd_service_descripto
  *     use.
  * @param label The label to use for communication. Usually the program name.
  *  Pass NULL to disable sending the label in requests to lockdownd.
+ * @param constructor_func Constructor function for the service client to create (e.g. afc_client_new())
+ * @param error_code Pointer to an int32_t that will receive the service start error code.
  *
  * @return SERVICE_E_SUCCESS on success, or a SERVICE_E_* error code
  *     otherwise.
@@ -160,7 +163,7 @@ service_error_t service_enable_ssl(service_client_t client);
 /**
  * Disable SSL for the given service client.
  *
- * @param client The connected service client for that SSL should be disabled.
+ * @param client The connected service client for which SSL should be disabled.
  *
  * @return SERVICE_E_SUCCESS on success,
  *     SERVICE_E_INVALID_ARG if client or client->connection is
@@ -169,9 +172,11 @@ service_error_t service_enable_ssl(service_client_t client);
 service_error_t service_disable_ssl(service_client_t client);
 
 /**
- * Disable SSL for the given service client without sending SSL terminate messages.
+ * Disable SSL for the given service client, optionally without sending SSL terminate messages.
  *
- * @param client The connected service client for that SSL should be disabled.
+ * @param client The connected service client for which SSL should be disabled.
+ * @param sslBypass A boolean value indicating wether to disable SSL with a proper
+ *     SSL shutdown (0), or bypass the shutdown (1).
  *
  * @return SERVICE_E_SUCCESS on success,
  *     SERVICE_E_INVALID_ARG if client or client->connection is
diff --git a/include/libimobiledevice/syslog_relay.h b/include/libimobiledevice/syslog_relay.h
index 89d9489..aae5d11 100644
--- a/include/libimobiledevice/syslog_relay.h
+++ b/include/libimobiledevice/syslog_relay.h
@@ -31,6 +31,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the syslog relay service */
 #define SYSLOG_RELAY_SERVICE_NAME "com.apple.syslog_relay"
 
 /** Error Codes */
@@ -44,7 +45,7 @@ typedef enum {
         SYSLOG_RELAY_E_UNKNOWN_ERROR   = -256
 } syslog_relay_error_t;
 
-typedef struct syslog_relay_client_private syslog_relay_client_private;
+typedef struct syslog_relay_client_private syslog_relay_client_private; /**< \private */
 typedef syslog_relay_client_private *syslog_relay_client_t; /**< The client handle. */
 
 /** Receives each character received from the device. */
@@ -170,7 +171,6 @@ syslog_relay_error_t syslog_relay_receive_with_timeout(syslog_relay_client_t cli
  * @param data Buffer that will be filled with the data received
  * @param size Number of bytes to receive
  * @param received Number of bytes received (can be NULL to ignore)
- * @param timeout Maximum time in milliseconds to wait for data.
  *
  * @return SYSLOG_RELAY_E_SUCCESS on success,
  *  SYSLOG_RELAY_E_INVALID_ARG when client or plist is NULL
diff --git a/include/libimobiledevice/webinspector.h b/include/libimobiledevice/webinspector.h
index da0759c..064ba91 100644
--- a/include/libimobiledevice/webinspector.h
+++ b/include/libimobiledevice/webinspector.h
@@ -31,6 +31,7 @@ extern "C" {
 #include <libimobiledevice/libimobiledevice.h>
 #include <libimobiledevice/lockdown.h>
 
+/** Service identifier passed to lockdownd_start_service() to start the webinspector service */
 #define WEBINSPECTOR_SERVICE_NAME "com.apple.webinspector"
 
 /** Error Codes */
@@ -45,7 +46,7 @@ typedef enum {
         WEBINSPECTOR_E_UNKNOWN_ERROR   = -256
 } webinspector_error_t;
 
-typedef struct webinspector_client_private webinspector_client_private;
+typedef struct webinspector_client_private webinspector_client_private; /**< \private */
 typedef webinspector_client_private *webinspector_client_t; /**< The client handle. */
 
 
@@ -118,7 +119,7 @@ webinspector_error_t webinspector_receive(webinspector_client_t client, plist_t
  * @param client The webinspector client to use for receiving
  * @param plist pointer to a plist_t that will point to the received plist
  *      upon successful return
- * @param timeout Maximum time in milliseconds to wait for data.
+ * @param timeout_ms Maximum time in milliseconds to wait for data.
  *
  * @return WEBINSPECTOR_E_SUCCESS on success,
  *      WEBINSPECTOR_E_INVALID_ARG when client or *plist is NULL,