Fix various API doc issues and typos

Partially based on an old patch by Adrian-Ken Rueegsegger.

man/ipsec.conf.5.in

@@ -826,7 +826,7 @@ as omitting
 completely. Using
 .B %dynamic
 can be used to define multiple dynamic selectors, each having a potentially
-different protocol/port definiton.
+different protocol/port definition.
 
 .TP
 .BR leftupdown " = <path>"

src/charon-cmd/charon-cmd.c

@@ -150,7 +150,7 @@ static int run()
 				return 0;
 			}
 			case SIGUSR1:
-			{	/* an error occured */
+			{	/* an error occurred */
 				charon->bus->alert(charon->bus, ALERT_SHUTDOWN_SIGNAL, sig);
 				return 1;
 			}

src/charon-cmd/cmd/cmd_connection.h

@@ -14,6 +14,11 @@
  */
 
 /**
+ * @defgroup charon-cmd charon-cmd
+ *
+ * @defgroup cmd cmd
+ * @ingroup charon-cmd
+ *
  * @defgroup cmd_connection cmd_connection
  * @{ @ingroup cmd
  */

src/frontends/osx/README.md

@@ -69,7 +69,7 @@ defined:
 	* _id_: client identity to use
 	* _channel_: XPC endpoint for this connection
 
-The start_connection() RPC returns just after the initation of the call and
+The start_connection() RPC returns just after the initiation of the call and
 does not wait for the connection to establish. Nonetheless does it have a
 return value to indicate if connection initiation could be triggered.
 

src/frontends/osx/charon-xpc/xpc_channels.h

@@ -14,6 +14,8 @@
  */
 
 /**
+ * @defgroup xpc charon-xpc
+ *
  * @defgroup xpc_channels xpc_channels
  * @{ @ingroup xpc
  */

src/libcharon/bus/listeners/listener.h

@@ -31,7 +31,7 @@ typedef struct listener_t listener_t;
 struct listener_t {
 
 	/**
-	 * Hook called if a critical alert is risen.
+	 * Hook called if a critical alert is raised.
 	 *
 	 * @param ike_sa	IKE_SA associated to the alert, if any
 	 * @param alert		kind of alert

src/libcharon/config/child_cfg.h

@@ -213,14 +213,14 @@ struct child_cfg_t {
 	u_int32_t (*get_inactivity)(child_cfg_t *this);
 
 	/**
-	 * Specific reqid to use for CHILD_SA
+	 * Specific reqid to use for CHILD_SA.
 	 *
 	 * @return				reqid
 	 */
 	u_int32_t (*get_reqid)(child_cfg_t *this);
 
 	/**
-	 * Optional mark for CHILD_SA
+	 * Optional mark for CHILD_SA.
 	 *
 	 * @param inbound		TRUE for inbound, FALSE for outbound
 	 * @return				mark
@@ -235,7 +235,7 @@ struct child_cfg_t {
 	u_int32_t (*get_tfc)(child_cfg_t *this);
 
 	/**
-	 * Sets two options needed for Mobile IPv6 interoperability
+	 * Sets two options needed for Mobile IPv6 interoperability.
 	 *
 	 * @param proxy_mode	use IPsec transport proxy mode (default FALSE)
 	 * @param install_policy install IPsec kernel policies (default TRUE)
@@ -244,7 +244,7 @@ struct child_cfg_t {
 												 bool install_policy);
 
 	/**
-	 * Check whether IPsec transport SA should be set up in proxy mode
+	 * Check whether IPsec transport SA should be set up in proxy mode.
 	 *
 	 * @return				TRUE, if proxy mode should be used
 	 *						FALSE, otherwise
@@ -252,7 +252,7 @@ struct child_cfg_t {
 	bool (*use_proxy_mode)(child_cfg_t *this);
 
 	/**
-	 * Check whether IPsec policies should be installed in the kernel
+	 * Check whether IPsec policies should be installed in the kernel.
 	 *
 	 * @return				TRUE, if IPsec kernel policies should be installed
 	 *						FALSE, otherwise

src/libcharon/config/peer_cfg.h

@@ -176,7 +176,7 @@ struct peer_cfg_t {
 	/**
 	 * Add an authentication config to the peer configuration.
 	 *
-	 * @param config		config to add
+	 * @param cfg			config to add
 	 * @param local			TRUE for local rules, FALSE for remote constraints
 	 */
 	void (*add_auth_cfg)(peer_cfg_t *this, auth_cfg_t *cfg, bool local);
@@ -190,7 +190,7 @@ struct peer_cfg_t {
 	enumerator_t* (*create_auth_cfg_enumerator)(peer_cfg_t *this, bool local);
 
 	/**
-	 * Should be sent a certificate for this connection?
+	 * Should a certificate be sent for this connection?
 	 *
 	 * @return			certificate sending policy
 	 */

src/libcharon/encoding/message.h

@@ -49,7 +49,7 @@ struct message_t {
 	 *
 	 * @param major_version	major version to set
 	 */
-	void (*set_major_version) (message_t *this,u_int8_t major_version);
+	void (*set_major_version) (message_t *this, u_int8_t major_version);
 
 	/**
 	 * Gets the IKE major version of the message.
@@ -63,7 +63,7 @@ struct message_t {
 	 *
 	 * @param minor_version	minor version to set
 	 */
-	void (*set_minor_version) (message_t *this,u_int8_t minor_version);
+	void (*set_minor_version) (message_t *this, u_int8_t minor_version);
 
 	/**
 	 * Gets the IKE minor version of the message.
@@ -77,7 +77,7 @@ struct message_t {
 	 *
 	 * @param message_id	message_id to set
 	 */
-	void (*set_message_id) (message_t *this,u_int32_t message_id);
+	void (*set_message_id) (message_t *this, u_int32_t message_id);
 
 	/**
 	 * Gets the Message ID of the message.
@@ -107,7 +107,7 @@ struct message_t {
 	 *
 	 * @param ike_sa_id		ike_sa_id to set
 	 */
-	void (*set_ike_sa_id) (message_t *this, ike_sa_id_t * ike_sa_id);
+	void (*set_ike_sa_id) (message_t *this, ike_sa_id_t *ike_sa_id);
 
 	/**
 	 * Gets the IKE_SA ID of the message.
@@ -123,7 +123,7 @@ struct message_t {
 	 *
 	 * @param exchange_type	exchange_type to set
 	 */
-	void (*set_exchange_type) (message_t *this,exchange_type_t exchange_type);
+	void (*set_exchange_type) (message_t *this, exchange_type_t exchange_type);
 
 	/**
 	 * Gets the exchange type of the message.

src/libcharon/sa/child_sa.h

@@ -231,7 +231,7 @@ struct child_sa_t {
 	/**
 	 * Override the DPD action specified by the CHILD_SA config.
 	 *
-	 * @param			close action to enforce
+	 * @param			dpd action to enforce
 	 */
 	void (*set_dpd_action)(child_sa_t *this, action_t action);
 
@@ -353,7 +353,7 @@ struct child_sa_t {
 	 * @param me		the new local host
 	 * @param other		the new remote host
 	 * @param vips		list of local virtual IPs
-	 * @param			TRUE to use UDP encapsulation for NAT traversal
+	 * @param encap		TRUE to use UDP encapsulation for NAT traversal
 	 * @return			SUCCESS or FAILED
 	 */
 	status_t (*update)(child_sa_t *this, host_t *me, host_t *other,

src/libcharon/sa/ike_sa.h

@@ -200,11 +200,11 @@ enum ike_condition_t {
 enum statistic_t {
 	/** Timestamp of SA establishement */
 	STAT_ESTABLISHED = 0,
-	/** Timestamp of scheudled rekeying */
+	/** Timestamp of scheduled rekeying */
 	STAT_REKEY,
-	/** Timestamp of scheudled reauthentication */
+	/** Timestamp of scheduled reauthentication */
 	STAT_REAUTH,
-	/** Timestamp of scheudled delete */
+	/** Timestamp of scheduled delete */
 	STAT_DELETE,
 	/** Timestamp of last inbound IKE packet */
 	STAT_INBOUND,
@@ -812,10 +812,8 @@ struct ike_sa_t {
 	/**
 	 * Sends a keep alive packet.
 	 *
-	 * To refresh NAT tables in a NAT router
+	 * To refresh NAT tables in a NAT router between the peers, periodic empty
-	 * between the peers, periodic empty
+	 * UDP packets are sent if no other traffic was sent.
-	 * UDP packets are sent if no other traffic
-	 * was sent.
 	 */
 	void (*send_keepalive) (ike_sa_t *this);
 

src/libcharon/sa/ike_sa_id.h

@@ -86,7 +86,7 @@ struct ike_sa_id_t {
 	bool (*equals) (ike_sa_id_t *this, ike_sa_id_t *other);
 
 	/**
-	 * Replace all values of a given ike_sa_id_t object with values.
+	 * Replace all values of a given ike_sa_id_t object with values
 	 * from another ike_sa_id_t object.
 	 *
 	 * After calling this function, both objects are equal.

src/libcharon/sa/ikev2/tasks/ike_cert_pre.h

@@ -28,7 +28,7 @@ typedef struct ike_cert_pre_t ike_cert_pre_t;
 #include <sa/task.h>
 
 /**
- * Task of type ike_cert_post, certificate processing before authentication.
+ * Task of type ike_cert_pre, certificate processing before authentication.
  */
 struct ike_cert_pre_t {
 

src/libcharon/sa/keymat.h

@@ -79,7 +79,7 @@ struct keymat_t {
 	 */
 	nonce_gen_t* (*create_nonce_gen)(keymat_t *this);
 
-	/*
+	/**
 	 * Get a AEAD transform to en-/decrypt and sign/verify IKE messages.
 	 *
 	 * @param in		TRUE for inbound (decrypt), FALSE for outbound (encrypt)

src/libcharon/sa/task.h

@@ -67,7 +67,7 @@ enum task_type_t {
 	TASK_CHILD_CREATE,
 	/** delete an established CHILD_SA */
 	TASK_CHILD_DELETE,
-	/** rekey an CHILD_SA */
+	/** rekey a CHILD_SA */
 	TASK_CHILD_REKEY,
 	/** IKEv1 main mode */
 	TASK_MAIN_MODE,

src/libhydra/kernel/kernel_interface.h

@@ -373,7 +373,7 @@ struct kernel_interface_t {
 	 *
 	 * The kernel interface uses refcounting, see add_ip().
 	 *
-	 * @param virtual_ip	virtual ip address to assign
+	 * @param virtual_ip	virtual ip address to remove
 	 * @param prefix		prefix length of the IP to uninstall, -1 for auto
 	 * @param wait			TRUE to wait untily IP is gone
 	 * @return				SUCCESS if operation completed
@@ -387,7 +387,7 @@ struct kernel_interface_t {
 	 * @param dst_net		destination net
 	 * @param prefixlen		destination net prefix length
 	 * @param gateway		gateway for this route
-	 * @param src_ip		sourc ip of the route
+	 * @param src_ip		source ip of the route
 	 * @param if_name		name of the interface the route is bound to
 	 * @return				SUCCESS if operation completed
 	 *						ALREADY_DONE if the route already exists
@@ -402,7 +402,7 @@ struct kernel_interface_t {
 	 * @param dst_net		destination net
 	 * @param prefixlen		destination net prefix length
 	 * @param gateway		gateway for this route
-	 * @param src_ip		sourc ip of the route
+	 * @param src_ip		source ip of the route
 	 * @param if_name		name of the interface the route is bound to
 	 * @return				SUCCESS if operation completed
 	 */
@@ -598,7 +598,7 @@ struct kernel_interface_t {
 							 char **kernel_name);
 
 	/**
-	 * Destroys a kernel_interface_manager_t object.
+	 * Destroys a kernel_interface_t object.
 	 */
 	void (*destroy) (kernel_interface_t *this);
 };

src/libhydra/kernel/kernel_net.h

@@ -134,7 +134,7 @@ struct kernel_net_t {
 	 *
 	 * The kernel interface uses refcounting, see add_ip().
 	 *
-	 * @param virtual_ip	virtual ip address to assign
+	 * @param virtual_ip	virtual ip address to remove
 	 * @param prefix		prefix length of the IP to uninstall, -1 for auto
 	 * @param wait			TRUE to wait until IP is gone
 	 * @return				SUCCESS if operation completed
@@ -148,7 +148,7 @@ struct kernel_net_t {
 	 * @param dst_net		destination net
 	 * @param prefixlen		destination net prefix length
 	 * @param gateway		gateway for this route
-	 * @param src_ip		sourc ip of the route
+	 * @param src_ip		source ip of the route
 	 * @param if_name		name of the interface the route is bound to
 	 * @return				SUCCESS if operation completed
 	 *						ALREADY_DONE if the route already exists
@@ -163,7 +163,7 @@ struct kernel_net_t {
 	 * @param dst_net		destination net
 	 * @param prefixlen		destination net prefix length
 	 * @param gateway		gateway for this route
-	 * @param src_ip		sourc ip of the route
+	 * @param src_ip		source ip of the route
 	 * @param if_name		name of the interface the route is bound to
 	 * @return				SUCCESS if operation completed
 	 */

src/libimcv/imv/imv_session.h

@@ -31,7 +31,7 @@
 typedef struct imv_session_t imv_session_t;
 
 /**
- * IMV session interface 
+ * IMV session interface
  */
 struct imv_session_t {
 
@@ -106,7 +106,7 @@ struct imv_session_t {
  * Create an imv_session_t instance
  *
  * @param session_id		Unique Session ID
- * @param conn_id			Associated Connection ID
+ * @param id				Associated Connection ID
  */
 imv_session_t* imv_session_create(int session_id, TNC_ConnectionID id);
 

src/libimcv/ita/ita_attr_device_id.h

@@ -41,7 +41,7 @@ struct ita_attr_device_id_t {
 /**
  * Creates an ita_attr_device_id_t object
  *
- * @param size				ITA Device ID attribute value
+ * @param value				ITA Device ID attribute value
  */
 pa_tnc_attr_t* ita_attr_device_id_create(chunk_t value);
 

src/libpttls/pt_tls.h

@@ -14,7 +14,7 @@
  */
 
 /**
- * @defgroup pt_tls pt_tls
+ * @defgroup pt_tls libpttls
  *
  * @addtogroup pt_tls
  * @{

src/libstrongswan/collections/array.h

@@ -28,7 +28,7 @@
  *
  * An array is a primitive object with associated functions to avoid the
  * overhead of an object with methods. It is efficient in memory usage, but
- * less effecient than a linked list in manipulating elements.
+ * less efficient than a linked list in manipulating elements.
  */
 typedef struct array_t array_t;
 
@@ -140,11 +140,12 @@ void array_insert_create(array_t **array, int idx, void *ptr);
 void array_insert_enumerator(array_t *array, int idx, enumerator_t *enumerator);
 
 /**
- * Remove an element from the array end.
+ * Remove an element from the array.
  *
  * If data is given, the element is copied to that position.
  *
  * @param array			array to remove element from, or NULL
+ * @param idx			index of the item to remove
  * @param data			data to copy element to, or NULL
  * @return				TRUE if idx existed and item removed
  */

src/libstrongswan/credentials/keys/public_key.h

@@ -192,7 +192,7 @@ struct public_key_t {
 	/**
 	 * Get the key in an encoded form as a chunk.
 	 *
-	 * @param type		type of the encoding, one of PRIVKEY_*
+	 * @param type		type of the encoding, one of PUBKEY_*
 	 * @param encoding	encoding of the key, allocated
 	 * @return			TRUE if encoding supported
 	 */

src/libstrongswan/crypto/aead.h

@@ -58,7 +58,7 @@ struct aead_t {
 	 * is returned in the encrypted chunk, the last get_icv_size() bytes
 	 * contain the verified ICV.
 	 *
-	 * @param encrypted		data to encrypt and verify
+	 * @param encrypted		data to decrypt and verify
 	 * @param assoc			associated data to verify
 	 * @param iv			initialization vector
 	 * @param plain			allocated result, if successful
@@ -105,7 +105,7 @@ struct aead_t {
 					chunk_t key) __attribute__((warn_unused_result));
 
 	/**
-	 * Destroy a aead_t.
+	 * Destroy an aead_t.
 	 */
 	void (*destroy)(aead_t *this);
 };

src/libstrongswan/networking/host.h

@@ -92,7 +92,7 @@ struct host_t {
 	 *
 	 * Returned chunk points to internal data.
 	 *
-	 * @return		address string,
+	 * @return		address blob
 	 */
 	chunk_t (*get_address) (host_t *this);
 
@@ -106,7 +106,7 @@ struct host_t {
 	/**
 	 * Set the port of this host
 	 *
-	 * @param port	port numer
+	 * @param port	port number
 	 */
 	void (*set_port) (host_t *this, u_int16_t port);
 
@@ -194,6 +194,7 @@ host_t *host_create_from_subnet(char *string, int *bits);
 /**
  * Create a netmask host having the first netbits bits set.
  *
+ * @param family		family of the netmask host
  * @param netbits		number of leading bits set in the host
  * @return				netmask host
  */

src/libstrongswan/processing/watcher.h

@@ -41,7 +41,7 @@ typedef enum watcher_event_t watcher_event_t;
  * and handle EAGAIN/EWOULDBLOCK gracefully.
  *
  * @param data		user data passed during registration
- * @param fd		file descriptor the event occured on
+ * @param fd		file descriptor the event occurred on
  * @param event		type of event
  * @return			TRUE to keep watching event, FALSE to unregister fd for event
  */

src/libstrongswan/utils/identification.h

@@ -241,7 +241,6 @@ struct identification_t {
 	 * no match at all, 1 means a bad match, and 2 a slightly better match.
 	 *
 	 * @param other		the ID containing one or more wildcards
-	 * @param wildcards	returns the number of wildcards, may be NULL
 	 * @return 			match value as described above
 	 */
 	id_match_t (*matches) (identification_t *this, identification_t *other);