Doxygen: Fix missing parameter warnings

This fixes almost all of the remaining warnings in our
doxygen. Mostly about missing parameters in otherwise
documented functions (completely undocumented functions
do not cause warnings).

Other changes:
 - Exclude out/ directory (used by CMakePresets.json)
 - Output doxygen warnings into a separate file, which
   can be used by CI systems to check for new warnings
 - Increase DOT_GRAPH_MAX_NODES to avoid warnings about
   some of the central header files (syshead.h and buffer.h)

Change-Id: I3bf775bbdea742575210606e174ccafe840677c9
Signed-off-by: Frank Lichtenheld <frank@lichtenheld.com>
Acked-by: Arne Schwabe <arne-openvpn@rfc2549.org>
Message-Id: <20250519143550.21761-1-gert@greenie.muc.de>
URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg31712.html
Signed-off-by: Gert Doering <gert@greenie.muc.de>

diff --git a/doc/doxygen/openvpn.doxyfile.in b/doc/doxygen/openvpn.doxyfile.in
index edecc549c8e3ff6e4251dcbce52061c203b1dc41..bdbc608954e119cb5b73da8819809730b368971a 100644 (file)
--- a/doc/doxygen/openvpn.doxyfile.in
+++ b/doc/doxygen/openvpn.doxyfile.in
@@ -852,7 +852,7 @@ WARN_FORMAT            = "$file:$line: $text"
 # messages should be written. If left blank the output is written to standard
 # error (stderr).
 
-WARN_LOGFILE           =
+WARN_LOGFILE           = @abs_top_builddir@/doc/doxygen.warnings.log
 
 #---------------------------------------------------------------------------
 # Configuration options related to the input files
@@ -909,7 +909,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+EXCLUDE                = @abs_top_srcdir@/out/
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -2571,7 +2571,7 @@ PLANTUML_INCLUDE_PATH  =
 # Minimum value: 0, maximum value: 10000, default value: 50.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_GRAPH_MAX_NODES    = 50
+DOT_GRAPH_MAX_NODES    = 150
 
 # The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs
 # generated by dot. A depth value of 3 means that only nodes reachable from the

diff --git a/src/openvpn/forward.c b/src/openvpn/forward.c
index ed4cdb4ec2a765be9e43a64d82f95830008af17e..022afdb929a329d3bffab4da4bee054e3f7c9749 100644 (file)
--- a/src/openvpn/forward.c
+++ b/src/openvpn/forward.c
@@ -1508,10 +1508,10 @@ process_incoming_tun(struct context *c, struct link_socket *out_sock)
  * IPv6 packet in buf and sends it directly back to the client via the tun
  * device when used on a client and via the link if used on the server.
  *
- * @param buf       - The buf containing the packet for which the icmp6
- *                    unreachable should be constructed.
- *
- * @param client    - determines whether to the send packet back via tun or link
+ * @param c         Tunnel context
+ * @param buf       The buf containing the packet for which the icmp6
+ *                  unreachable should be constructed.
+ * @param client    Determines whether to the send packet back via tun or link
  */
 void
 ipv6_send_icmp_unreachable(struct context *c, struct buffer *buf, bool client)

diff --git a/src/openvpn/fragment.h b/src/openvpn/fragment.h
index 88f6053c427bd86a6b5aa18385d4e4d969b50bfd..91f4a26e40d484f8cc6d7e0eafb8164d01334655 100644 (file)
--- a/src/openvpn/fragment.h
+++ b/src/openvpn/fragment.h
@@ -443,10 +443,11 @@ void fragment_wakeup(struct fragment_master *f, struct frame *frame);
  * packets which have not yet been reassembled completely but are already
  * older than their time-to-live.
  *
- * @param f            - The \c fragment_master structure for this VPN
- *                       tunnel.
- * @param frame        - The packet geometry parameters for this VPN
- *                       tunnel.
+ * @param[in] f        The \c fragment_master structure for this VPN
+ *                     tunnel.
+ * @param[in] frame    The packet geometry parameters for this VPN
+ *                     tunnel.
+ * @param[out] tv      Will be set to time for next housekeeping.
  */
 static inline void
 fragment_housekeeping(struct fragment_master *f, struct frame *frame, struct timeval *tv)

diff --git a/src/openvpn/manage.c b/src/openvpn/manage.c
index 567b6eadcd2eae526392f0abb1fe9a6fc4456c60..3936320b010b795af1ec2d5ab3757b4bc02d2641 100644 (file)
--- a/src/openvpn/manage.c
+++ b/src/openvpn/manage.c
@@ -1059,8 +1059,9 @@ parse_uint(const char *str, const char *what, unsigned int *uint)
  * @param man           The management interface struct
  * @param cid_str       The CID in string form
  * @param kid_str       The key ID in string form
- * @param extra         The string to be send to the client containing
+ * @param extra         The string to be sent to the client containing
  *                      the information of the additional steps
+ * @param timeout_str   The timeout value in string form
  */
 static void
 man_client_pending_auth(struct management *man, const char *cid_str,

diff --git a/src/openvpn/mudp.h b/src/openvpn/mudp.h
index 37752e1384b9f59d552a7fead93cdb5c3003df5a..2fa4c4dfcfbcf6e8b76b1aca0071d030c5e0f599 100644 (file)
--- a/src/openvpn/mudp.h
+++ b/src/openvpn/mudp.h
@@ -46,12 +46,13 @@ void multi_process_io_udp(struct multi_context *m, struct link_socket *sock);
  * it.  If no entry exists, this function handles its creation, and if
  * successful, returns the newly created instance.
  *
- * @param m           - The single multi_context structure.
- * @param sock        - Listening socket where this instance is connecting to
+ * @param m            The single multi_context structure.
+ * @param[out] floated Returns whether the client has floated.
+ * @param sock         Listening socket where this instance is connecting to
  *
  * @return A pointer to a multi_instance if one already existed for the
  *     packet's source address or if one was a newly created successfully.
- *      NULL if one did not yet exist and a new one was not created.
+ *     NULL if one did not yet exist and a new one was not created.
  */
 struct multi_instance *multi_get_create_instance_udp(struct multi_context *m, bool *floated,
                                                      struct link_socket *sock);

diff --git a/src/openvpn/multi.c b/src/openvpn/multi.c
index 80dd0c041327bda6656879daa3a718652ed0ec86..8b5900f7306202592812b0d54557432851d0ccbc 100644 (file)
--- a/src/openvpn/multi.c
+++ b/src/openvpn/multi.c
@@ -4247,7 +4247,7 @@ multi_assign_peer_id(struct multi_context *m, struct multi_instance *mi)
  * Main event loop for OpenVPN in point-to-multipoint server mode.
  * @ingroup eventloop
  *
- * @param top - Top-level context structure.
+ * @param multi context structure
  */
 static void
 tunnel_server_loop(struct multi_context *multi)

diff --git a/src/openvpn/options.c b/src/openvpn/options.c
index 6672b5c755eeda3c24a9085cbb0b2f85b8f45ffb..bcc18a514407e4f7c5bbdeb767f4ce88249e4bd6 100644 (file)
--- a/src/openvpn/options.c
+++ b/src/openvpn/options.c
@@ -3500,6 +3500,7 @@ options_postprocess_cipher(struct options *o)
  * altered to guarantee compatibility with the version specified by the
  * user via --compat-mode.
  *
+ * @param o         Options state
  * @param version   need compatibility with openvpn versions before the
  *                  one specified (20401 = before 2.4.1)
  * @return          whether compatibility should be enabled

diff --git a/src/openvpn/ssl.h b/src/openvpn/ssl.h
index c32cb6cf9d00f9861eae69b93d203936302357ab..c158b35ca9709ea83bc3da24e394e9c39f9abb77 100644 (file)
--- a/src/openvpn/ssl.h
+++ b/src/openvpn/ssl.h
@@ -281,13 +281,14 @@ int tls_multi_process(struct tls_multi *multi,
  * packet is inserted into the Reliability Layer and will be handled
  * later.
  *
- * @param multi - The TLS multi structure associated with the VPN tunnel
+ * @param[in]  multi    The TLS multi structure associated with the VPN tunnel
  *     of this packet.
- * @param from - The source address of the packet.
- * @param buf - A buffer structure containing the incoming packet.
- * @param opt - Returns a crypto options structure with the appropriate security
- *     parameters to handle the packet if it is a data channel packet.
- * @param ad_start - Returns a pointer to the start of the authenticated data of
+ * @param[in]  from     The source address of the packet.
+ * @param[in]  buf      buffer structure containing the incoming packet.
+ * @param[out] opt      Returns a crypto options structure with the appropriate
+ *     security parameters to handle the packet if it is a data channel packet.
+ * @param[in] floated   Set whether the peer is allowed to have floated.
+ * @param[out] ad_start Returns a pointer to the start of the authenticated data
  *     of this packet
  *
  * @return

diff --git a/src/openvpn/ssl_backend.h b/src/openvpn/ssl_backend.h
index e25727f0198ec2149887eab2c5bdd1ce55230608..21abacc7d36c38beb2cf0a7958ce472bd96fa397 100644 (file)
--- a/src/openvpn/ssl_backend.h
+++ b/src/openvpn/ssl_backend.h
@@ -241,6 +241,8 @@ void tls_ctx_load_ecdh_params(struct tls_root_ctx *ctx, const char *curve_name
  *                              a string containing the information in the case
  *                              of inline files.
  * @param pkcs12_file_inline    True if pkcs12_file is an inline file.
+ * @param load_ca_file          True if CAs from the file should be added to
+ *                              the cert store and be trusted.
  *
  * @return                      1 if an error occurred, 0 if parsing was
  *                              successful.
@@ -313,6 +315,9 @@ int tls_ctx_use_management_external_key(struct tls_root_ctx *ctx);
  *                              inline files.
  * @param ca_file_inline        True if ca_file is an inline file
  * @param ca_path               The path to load the CAs from
+ * @param tls_server            True if we are the server side of the TLS
+ *                              connection and should use the CA for verifying
+ *                              client certificates
  */
 void tls_ctx_load_ca(struct tls_root_ctx *ctx, const char *ca_file,
                      bool ca_file_inline, const char *ca_path, bool tls_server);

diff --git a/src/openvpn/ssl_ncp.h b/src/openvpn/ssl_ncp.h
index 36be65b58731b42505bb0b6605c58f7791716de1..d2e8300b7a9b29fe7b22a02be2b67a801db08643 100644 (file)
--- a/src/openvpn/ssl_ncp.h
+++ b/src/openvpn/ssl_ncp.h
@@ -66,7 +66,10 @@ check_pull_client_ncp(struct context *c, int found);
  * Make sure to call tls_session_update_crypto_params() after calling this
  * function.
  *
- * @param gc   gc arena that is ONLY used to allocate the returned string
+ * @param server_list   Our own cipher list
+ * @param peer_info     Peer information
+ * @param remote_cipher Fallback cipher, ignored if peer sent \c IV_CIPHERS
+ * @param gc            gc arena that is used to allocate the returned string
  *
  * @returns NULL if no common cipher is available, otherwise the best common
  * cipher

diff --git a/src/openvpn/ssl_pkt.c b/src/openvpn/ssl_pkt.c
index 41299f462db4287b797fb3a7e5d58c869e56a72a..ac6520309a24815bcdc5e384a62ae308f4b8cbc4 100644 (file)
--- a/src/openvpn/ssl_pkt.c
+++ b/src/openvpn/ssl_pkt.c
@@ -296,8 +296,8 @@ free_tls_pre_decrypt_state(struct tls_pre_decrypt_state *state)
 /*
  * This function is similar to tls_pre_decrypt, except it is called
  * when we are in server mode and receive an initial incoming
- * packet.  Note that we don't modify
- * any state in our parameter objects.  The purpose is solely to
+ * packet.  Note that we don't modify any state in our parameter
+ * objects except state.  The purpose is solely to
  * determine whether we should generate a client instance
  * object, in which case true is returned.
  *

diff --git a/src/openvpn/ssl_pkt.h b/src/openvpn/ssl_pkt.h
index e78239160f99f5859ccc4836ef07a6417c30d271..0cd4127c7f33599b06acf25f0748fd0eca4d5d23 100644 (file)
--- a/src/openvpn/ssl_pkt.h
+++ b/src/openvpn/ssl_pkt.h
@@ -109,10 +109,6 @@ struct tls_pre_decrypt_state {
     struct session_id server_session_id;
 };
 
-/**
- *
- * @param state
- */
 void free_tls_pre_decrypt_state(struct tls_pre_decrypt_state *state);
 
 /**
@@ -137,10 +133,11 @@ void free_tls_pre_decrypt_state(struct tls_pre_decrypt_state *state);
  *
  * This function is only used in the UDP p2mp server code path
  *
- * @param tas - The standalone TLS authentication setting structure for
+ * @param[in] tas    The standalone TLS authentication setting structure for
  *     this process.
- * @param from - The source address of the packet.
- * @param buf - A buffer structure containing the incoming packet.
+ * @param[out] state The state struct to store information in.
+ * @param[in] from   The source address of the packet.
+ * @param[in] buf    buffer structure containing the incoming packet.
  *
  * @return
  * @li True if the packet is valid and a new VPN tunnel should be created

diff --git a/src/openvpn/ssl_util.h b/src/openvpn/ssl_util.h
index 71a37d4c074a2d94a8f2dcf07a495e45afcea88b..25f169c63f4da8dc28bc0f62b8a54a9515f654dd 100644 (file)
--- a/src/openvpn/ssl_util.h
+++ b/src/openvpn/ssl_util.h
@@ -39,6 +39,7 @@
  *
  * @param peer_info     The peer's peer_info
  * @param var           The variable *including* =, e.g. IV_CIPHERS=
+ * @param gc            GC arena to allocate return value in
  *
  * @return  The content of the variable as NULL terminated string or NULL if the
  *          variable cannot be found.

diff --git a/src/openvpn/ssl_verify.h b/src/openvpn/ssl_verify.h
index 7a4d44ad95213ed33db21f68233dde3ce8dda13b..6d269b2689c2461cb5e197c913ee239f36cfe047 100644 (file)
--- a/src/openvpn/ssl_verify.h
+++ b/src/openvpn/ssl_verify.h
@@ -153,7 +153,7 @@ const char *tls_common_name(const struct tls_multi *multi, const bool null);
 /**
  * Sets the common name field for the given tunnel
  *
- * @param multi         The tunnel to set the common name for
+ * @param session       The session to set the common name for
  * @param common_name   The name to set the common name to
  */
 void

diff --git a/src/openvpn/tls_crypt.h b/src/openvpn/tls_crypt.h
index 87e9867fa7fcbd92ea346d83856bfd5fc143d4fd..42545d17174f2d035ba4494914ffefda965d22d0 100644 (file)
--- a/src/openvpn/tls_crypt.h
+++ b/src/openvpn/tls_crypt.h
@@ -204,6 +204,7 @@ void tls_crypt_v2_init_client_key(struct key_ctx_bi *key,
  * @param buf   Buffer containing a received P_CONTROL_HARD_RESET_CLIENT_V3
  *              message.
  * @param ctx   tls-wrap context to be initialized with the client key.
+ * @param opt   TLS options, used for \c tls-crypt-v2-verify script.
  *
  * @param initial_packet    whether this is the initial packet of the
  *                          connection. Only in these scenarios unwrapping