From 0ceb2888150afb793c6d8ace1ecdc70efd390a45 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Thu, 18 Jul 2013 17:27:11 +0200 Subject: [PATCH] Fix various API doc issues and typos Partially based on an old patch by Adrian-Ken Rueegsegger. --- man/ipsec.conf.5.in | 2 +- src/charon-cmd/charon-cmd.c | 2 +- src/charon-cmd/cmd/cmd_connection.h | 5 +++++ src/frontends/osx/README.md | 2 +- src/frontends/osx/charon-xpc/xpc_channels.h | 2 ++ src/libcharon/bus/listeners/listener.h | 2 +- src/libcharon/config/child_cfg.h | 10 +++++----- src/libcharon/config/peer_cfg.h | 4 ++-- src/libcharon/encoding/message.h | 10 +++++----- src/libcharon/sa/child_sa.h | 4 ++-- src/libcharon/sa/ike_sa.h | 12 +++++------- src/libcharon/sa/ike_sa_id.h | 2 +- src/libcharon/sa/ikev2/tasks/ike_cert_pre.h | 2 +- src/libcharon/sa/keymat.h | 2 +- src/libcharon/sa/task.h | 2 +- src/libhydra/kernel/kernel_interface.h | 8 ++++---- src/libhydra/kernel/kernel_net.h | 6 +++--- src/libimcv/imv/imv_session.h | 4 ++-- src/libimcv/ita/ita_attr_device_id.h | 2 +- src/libpttls/pt_tls.h | 2 +- src/libstrongswan/collections/array.h | 5 +++-- src/libstrongswan/credentials/keys/public_key.h | 2 +- src/libstrongswan/crypto/aead.h | 4 ++-- src/libstrongswan/networking/host.h | 5 +++-- src/libstrongswan/processing/watcher.h | 2 +- src/libstrongswan/utils/identification.h | 1 - 26 files changed, 55 insertions(+), 49 deletions(-) diff --git a/man/ipsec.conf.5.in b/man/ipsec.conf.5.in index 2a933350d..4c64e86ca 100644 --- a/man/ipsec.conf.5.in +++ b/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 " = " diff --git a/src/charon-cmd/charon-cmd.c b/src/charon-cmd/charon-cmd.c index 494e4f84e..5f4787b58 100644 --- a/src/charon-cmd/charon-cmd.c +++ b/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; } diff --git a/src/charon-cmd/cmd/cmd_connection.h b/src/charon-cmd/cmd/cmd_connection.h index 0f167bfdc..221802617 100644 --- a/src/charon-cmd/cmd/cmd_connection.h +++ b/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 */ diff --git a/src/frontends/osx/README.md b/src/frontends/osx/README.md index bd24cce1b..66799b844 100644 --- a/src/frontends/osx/README.md +++ b/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. diff --git a/src/frontends/osx/charon-xpc/xpc_channels.h b/src/frontends/osx/charon-xpc/xpc_channels.h index 125a81f1d..99e4d77e6 100644 --- a/src/frontends/osx/charon-xpc/xpc_channels.h +++ b/src/frontends/osx/charon-xpc/xpc_channels.h @@ -14,6 +14,8 @@ */ /** + * @defgroup xpc charon-xpc + * * @defgroup xpc_channels xpc_channels * @{ @ingroup xpc */ diff --git a/src/libcharon/bus/listeners/listener.h b/src/libcharon/bus/listeners/listener.h index ef4daced2..57445df01 100644 --- a/src/libcharon/bus/listeners/listener.h +++ b/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 diff --git a/src/libcharon/config/child_cfg.h b/src/libcharon/config/child_cfg.h index 6e8829a47..20d1fa811 100644 --- a/src/libcharon/config/child_cfg.h +++ b/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 diff --git a/src/libcharon/config/peer_cfg.h b/src/libcharon/config/peer_cfg.h index 80913beba..e62e03ec5 100644 --- a/src/libcharon/config/peer_cfg.h +++ b/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 */ diff --git a/src/libcharon/encoding/message.h b/src/libcharon/encoding/message.h index 2c11e4581..7631a7c3a 100644 --- a/src/libcharon/encoding/message.h +++ b/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. diff --git a/src/libcharon/sa/child_sa.h b/src/libcharon/sa/child_sa.h index 44c529391..ed52d60b1 100644 --- a/src/libcharon/sa/child_sa.h +++ b/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, diff --git a/src/libcharon/sa/ike_sa.h b/src/libcharon/sa/ike_sa.h index 625859a3f..00c16c05e 100644 --- a/src/libcharon/sa/ike_sa.h +++ b/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 - * between the peers, periodic empty - * UDP packets are sent if no other traffic - * was sent. + * To refresh NAT tables in a NAT router between the peers, periodic empty + * UDP packets are sent if no other traffic was sent. */ void (*send_keepalive) (ike_sa_t *this); diff --git a/src/libcharon/sa/ike_sa_id.h b/src/libcharon/sa/ike_sa_id.h index 227683d1c..5eb754e95 100644 --- a/src/libcharon/sa/ike_sa_id.h +++ b/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. diff --git a/src/libcharon/sa/ikev2/tasks/ike_cert_pre.h b/src/libcharon/sa/ikev2/tasks/ike_cert_pre.h index ac1a85c29..c1f8635ce 100644 --- a/src/libcharon/sa/ikev2/tasks/ike_cert_pre.h +++ b/src/libcharon/sa/ikev2/tasks/ike_cert_pre.h @@ -28,7 +28,7 @@ typedef struct ike_cert_pre_t ike_cert_pre_t; #include /** - * 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 { diff --git a/src/libcharon/sa/keymat.h b/src/libcharon/sa/keymat.h index 02db5ca58..bc40b3d92 100644 --- a/src/libcharon/sa/keymat.h +++ b/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) diff --git a/src/libcharon/sa/task.h b/src/libcharon/sa/task.h index c37221a77..f2c4299cc 100644 --- a/src/libcharon/sa/task.h +++ b/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, diff --git a/src/libhydra/kernel/kernel_interface.h b/src/libhydra/kernel/kernel_interface.h index f73578167..1d96f1c35 100644 --- a/src/libhydra/kernel/kernel_interface.h +++ b/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); }; diff --git a/src/libhydra/kernel/kernel_net.h b/src/libhydra/kernel/kernel_net.h index 165036231..8c448ddbc 100644 --- a/src/libhydra/kernel/kernel_net.h +++ b/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 */ diff --git a/src/libimcv/imv/imv_session.h b/src/libimcv/imv/imv_session.h index d38b2aca5..6b94523b8 100644 --- a/src/libimcv/imv/imv_session.h +++ b/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); diff --git a/src/libimcv/ita/ita_attr_device_id.h b/src/libimcv/ita/ita_attr_device_id.h index 558a8e055..ffacdba1e 100644 --- a/src/libimcv/ita/ita_attr_device_id.h +++ b/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); diff --git a/src/libpttls/pt_tls.h b/src/libpttls/pt_tls.h index cb8bde05c..92a040f3f 100644 --- a/src/libpttls/pt_tls.h +++ b/src/libpttls/pt_tls.h @@ -14,7 +14,7 @@ */ /** - * @defgroup pt_tls pt_tls + * @defgroup pt_tls libpttls * * @addtogroup pt_tls * @{ diff --git a/src/libstrongswan/collections/array.h b/src/libstrongswan/collections/array.h index 3e6180b54..0dc7b2250 100644 --- a/src/libstrongswan/collections/array.h +++ b/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 */ diff --git a/src/libstrongswan/credentials/keys/public_key.h b/src/libstrongswan/credentials/keys/public_key.h index fdbe17f2c..2afcf8325 100644 --- a/src/libstrongswan/credentials/keys/public_key.h +++ b/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 */ diff --git a/src/libstrongswan/crypto/aead.h b/src/libstrongswan/crypto/aead.h index ec526a3d9..f3959f8f3 100644 --- a/src/libstrongswan/crypto/aead.h +++ b/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); }; diff --git a/src/libstrongswan/networking/host.h b/src/libstrongswan/networking/host.h index ae25076ed..4fc6cf35c 100644 --- a/src/libstrongswan/networking/host.h +++ b/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 */ diff --git a/src/libstrongswan/processing/watcher.h b/src/libstrongswan/processing/watcher.h index 02d9188f0..6e158cec2 100644 --- a/src/libstrongswan/processing/watcher.h +++ b/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 */ diff --git a/src/libstrongswan/utils/identification.h b/src/libstrongswan/utils/identification.h index 00d740765..e62446879 100644 --- a/src/libstrongswan/utils/identification.h +++ b/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);