From: Frank Lichtenheld <fr...@lichtenheld.com> 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 <fr...@lichtenheld.com> Acked-by: Arne Schwabe <arne-open...@rfc2549.org> --- This change was reviewed on Gerrit and approved by at least one developer. I request to merge it to master. Gerrit URL: https://gerrit.openvpn.net/c/openvpn/+/848 This mail reflects revision 6 of this Change. Acked-by according to Gerrit (reflected above): Arne Schwabe <arne-open...@rfc2549.org> diff --git a/doc/doxygen/openvpn.doxyfile.in b/doc/doxygen/openvpn.doxyfile.in index edecc54..bdbc608 100644 --- a/doc/doxygen/openvpn.doxyfile.in +++ b/doc/doxygen/openvpn.doxyfile.in @@ -852,7 +852,7 @@ # 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 @@ # 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 @@ # 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 ed4cdb4..022afdb 100644 --- a/src/openvpn/forward.c +++ b/src/openvpn/forward.c @@ -1508,10 +1508,10 @@ * 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 88f6053..91f4a26 100644 --- a/src/openvpn/fragment.h +++ b/src/openvpn/fragment.h @@ -443,10 +443,11 @@ * 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 567b6ea..3936320 100644 --- a/src/openvpn/manage.c +++ b/src/openvpn/manage.c @@ -1059,8 +1059,9 @@ * @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 37752e1..2fa4c4d 100644 --- a/src/openvpn/mudp.h +++ b/src/openvpn/mudp.h @@ -46,12 +46,13 @@ * 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 80dd0c0..8b5900f 100644 --- a/src/openvpn/multi.c +++ b/src/openvpn/multi.c @@ -4247,7 +4247,7 @@ * 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 6672b5c..bcc18a5 100644 --- a/src/openvpn/options.c +++ b/src/openvpn/options.c @@ -3500,6 +3500,7 @@ * 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 c32cb6c..c158b35 100644 --- a/src/openvpn/ssl.h +++ b/src/openvpn/ssl.h @@ -281,13 +281,14 @@ * 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 e25727f..21abacc 100644 --- a/src/openvpn/ssl_backend.h +++ b/src/openvpn/ssl_backend.h @@ -241,6 +241,8 @@ * 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 @@ * 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 36be65b..d2e8300 100644 --- a/src/openvpn/ssl_ncp.h +++ b/src/openvpn/ssl_ncp.h @@ -66,7 +66,10 @@ * 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 41299f4..ac65203 100644 --- a/src/openvpn/ssl_pkt.c +++ b/src/openvpn/ssl_pkt.c @@ -296,8 +296,8 @@ /* * 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 e782391..0cd4127 100644 --- a/src/openvpn/ssl_pkt.h +++ b/src/openvpn/ssl_pkt.h @@ -109,10 +109,6 @@ struct session_id server_session_id; }; -/** - * - * @param state - */ void free_tls_pre_decrypt_state(struct tls_pre_decrypt_state *state); /** @@ -137,10 +133,11 @@ * * 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 71a37d4..25f169c 100644 --- 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 7a4d44a..6d269b2 100644 --- a/src/openvpn/ssl_verify.h +++ b/src/openvpn/ssl_verify.h @@ -153,7 +153,7 @@ /** * 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 87e9867..42545d1 100644 --- a/src/openvpn/tls_crypt.h +++ b/src/openvpn/tls_crypt.h @@ -204,6 +204,7 @@ * @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 _______________________________________________ Openvpn-devel mailing list Openvpn-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/openvpn-devel
