SSL_handle_events(): Minor fixes to documentation

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/20879)

4 files changed, 15 insertions, 13 deletions

diff --git a/doc/man3/DTLSv1_handle_timeout.pod b/doc/man3/DTLSv1_handle_timeout.pod
index bb2bafe4e4..4c7dfff7f8 100644
--- a/doc/man3/DTLSv1_handle_timeout.pod
+++ b/doc/man3/DTLSv1_handle_timeout.pod
@@ -22,7 +22,7 @@ when to call DTLSv1_handle_timeout().
 This function is only applicable to DTLS or QUIC SSL objects. It returns 0 if
 called on any other kind of SSL object.
 
-L<SSL_handle_events(3)> supersedes all use cases for this this function and may
+L<SSL_handle_events(3)> supersedes all use cases for this function and may
 be used instead of it.
 
 =head1 RETURN VALUES
diff --git a/doc/man3/SSL_get_event_timeout.pod b/doc/man3/SSL_get_event_timeout.pod
index e0a1c46556..8649cb4f03 100644
--- a/doc/man3/SSL_get_event_timeout.pod
+++ b/doc/man3/SSL_get_event_timeout.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-SSL_get_event_timeout - determine when an SSL object next needs to be ticked
+SSL_get_event_timeout - determine when an SSL object next needs to have events
+handled
 
 =head1 SYNOPSIS
 
@@ -24,8 +25,8 @@ cases applies:
 
 =item
 
-The SSL object has events which need to be handled immediately; I<*tv> is set to
-zero and I<*is_infinite> is set to 0.
+The SSL object has events which need to be handled immediately; The fields of
+I<*tv> are set to 0 and I<*is_infinite> is set to 0.
 
 =item
 
@@ -53,7 +54,7 @@ considered a success condition.
 Note that the value output by a call to SSL_get_event_timeout() may change as a
 result of other calls to the SSL object.
 
-Once the timeout expires, SSL_handle_events() should be called to handle any
+Once the timeout expires, L<SSL_handle_events(3)> should be called to handle any
 internal processing which is due; for more information, see
 L<SSL_handle_events(3)>.
 
diff --git a/doc/man3/SSL_handle_events.pod b/doc/man3/SSL_handle_events.pod
index 85184ec8eb..e02eb33ee1 100644
--- a/doc/man3/SSL_handle_events.pod
+++ b/doc/man3/SSL_handle_events.pod
@@ -38,10 +38,10 @@ cases of L<DTLSv1_handle_timeout(3)>, it should be preferred for new
 applications which do not require support for OpenSSL 3.1 or older.
 
 When using DTLS, an application must call SSL_handle_events() as indicated by
-calls to L<SSL_get_event_timeout(3)>; ticking is not performed automatically by
-calls to other SSL functions such as L<SSL_read(3)> or L<SSL_write(3)>. Note
-that this is different to QUIC which also performs ticking implicitly; see
-below.
+calls to L<SSL_get_event_timeout(3)>; event handling is not performed
+automatically by calls to other SSL functions such as L<SSL_read(3)> or
+L<SSL_write(3)>. Note that this is different to QUIC which also performs event
+handling implicitly; see below.
 
 =item QUIC connection SSL objects
 
diff --git a/ssl/quic/quic_impl.c b/ssl/quic/quic_impl.c
index d9ee5cf96e..d00f4455b0 100644
--- a/ssl/quic/quic_impl.c
+++ b/ssl/quic/quic_impl.c
@@ -839,7 +839,7 @@ static int xso_blocking_mode(const QUIC_XSO *xso)
         && xso->conn->can_poll_net_wbio;
 }
 
-/* SSL_handle_events; handles events by ticking the reactor. */
+/* SSL_handle_events; performs QUIC I/O and timeout processing. */
 QUIC_TAKES_LOCK
 int ossl_quic_handle_events(SSL *s)
 {
@@ -856,9 +856,10 @@ int ossl_quic_handle_events(SSL *s)
 
 /*
  * SSL_get_event_timeout. Get the time in milliseconds until the SSL object
- * should be ticked by the application by calling SSL_handle_events(). tv is set
- * to 0 if the object should be ticked immediately. If no timeout is currently
- * active, *is_infinite is set to 1 and the value of *tv is undefined.
+ * should next have events handled by the application by calling
+ * SSL_handle_events(). tv is set to 0 if the object should have events handled
+ * immediately. If no timeout is currently active, *is_infinite is set to 1 and
+ * the value of *tv is undefined.
  */
 QUIC_TAKES_LOCK
 int ossl_quic_get_event_timeout(SSL *s, struct timeval *tv, int *is_infinite)