Fix various API doc issues and typos
authorTobias Brunner <tobias@strongswan.org>
Thu, 18 Jul 2013 15:27:11 +0000 (17:27 +0200)
committerTobias Brunner <tobias@strongswan.org>
Thu, 18 Jul 2013 16:30:36 +0000 (18:30 +0200)
Partially based on an old patch by Adrian-Ken Rueegsegger.

26 files changed:
man/ipsec.conf.5.in
src/charon-cmd/charon-cmd.c
src/charon-cmd/cmd/cmd_connection.h
src/frontends/osx/README.md
src/frontends/osx/charon-xpc/xpc_channels.h
src/libcharon/bus/listeners/listener.h
src/libcharon/config/child_cfg.h
src/libcharon/config/peer_cfg.h
src/libcharon/encoding/message.h
src/libcharon/sa/child_sa.h
src/libcharon/sa/ike_sa.h
src/libcharon/sa/ike_sa_id.h
src/libcharon/sa/ikev2/tasks/ike_cert_pre.h
src/libcharon/sa/keymat.h
src/libcharon/sa/task.h
src/libhydra/kernel/kernel_interface.h
src/libhydra/kernel/kernel_net.h
src/libimcv/imv/imv_session.h
src/libimcv/ita/ita_attr_device_id.h
src/libpttls/pt_tls.h
src/libstrongswan/collections/array.h
src/libstrongswan/credentials/keys/public_key.h
src/libstrongswan/crypto/aead.h
src/libstrongswan/networking/host.h
src/libstrongswan/processing/watcher.h
src/libstrongswan/utils/identification.h

index 2a93335..4c64e86 100644 (file)
@@ -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>"
index 494e4f8..5f4787b 100644 (file)
@@ -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;
                        }
index 0f167bf..2218026 100644 (file)
  */
 
 /**
+ * @defgroup charon-cmd charon-cmd
+ *
+ * @defgroup cmd cmd
+ * @ingroup charon-cmd
+ *
  * @defgroup cmd_connection cmd_connection
  * @{ @ingroup cmd
  */
index bd24cce..66799b8 100644 (file)
@@ -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.
 
index 125a81f..99e4d77 100644 (file)
@@ -14,6 +14,8 @@
  */
 
 /**
+ * @defgroup xpc charon-xpc
+ *
  * @defgroup xpc_channels xpc_channels
  * @{ @ingroup xpc
  */
index ef4dace..57445df 100644 (file)
@@ -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
index 6e8829a..20d1fa8 100644 (file)
@@ -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
index 80913be..e62e03e 100644 (file)
@@ -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
         */
index 2c11e45..7631a7c 100644 (file)
@@ -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.
index 44c5293..ed52d60 100644 (file)
@@ -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,
index 625859a..00c16c0 100644 (file)
@@ -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);
 
index 227683d..5eb754e 100644 (file)
@@ -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.
index ac1a85c..c1f8635 100644 (file)
@@ -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 {
 
index 02db5ca..bc40b3d 100644 (file)
@@ -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)
index c37221a..f2c4299 100644 (file)
@@ -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,
index f735781..1d96f1c 100644 (file)
@@ -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);
 };
index 1650362..8c448dd 100644 (file)
@@ -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
         */
index d38b2ac..6b94523 100644 (file)
@@ -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);
 
index 558a8e0..ffacdba 100644 (file)
@@ -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);
 
index cb8bde0..92a040f 100644 (file)
@@ -14,7 +14,7 @@
  */
 
 /**
- * @defgroup pt_tls pt_tls
+ * @defgroup pt_tls libpttls
  *
  * @addtogroup pt_tls
  * @{
index 3e6180b..0dc7b22 100644 (file)
@@ -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
  */
index fdbe17f..2afcf83 100644 (file)
@@ -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
         */
index ec526a3..f3959f8 100644 (file)
@@ -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);
 };
index ae25076..4fc6cf3 100644 (file)
@@ -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
  */
index 02d9188..6e158ce 100644 (file)
@@ -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
  */
index 00d7407..e624468 100644 (file)
@@ -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);