rbs 4.0.0.dev.4 → 4.0.0

data/stdlib/openssl/0/openssl.rbs

@@ -120,8 +120,8 @@
 # supported (see below).
 #
 # PKCS5 supports PBKDF2 as it was specified in PKCS#5
-# [v2.0](http://www.rsa.com/rsalabs/node.asp?id=2127). It still uses a password,
-# a salt, and additionally a number of iterations that will slow the key
+# v2.0[http://www.rsa.com/rsalabs/node.asp?id=2127]. It still uses a password, a
+# salt, and additionally a number of iterations that will slow the key
 # derivation process down. The slower this is, the more work it requires being
 # able to brute-force the resulting key.
 #
@@ -367,7 +367,7 @@
 # ## SSL and TLS Connections
 #
 # Using our created key and certificate we can create an SSL or TLS connection.
-# An SSLContext is used to set up an SSL session.
+# An OpenSSL::SSL::SSLContext is used to set up an SSL session.
 #
 #     context = OpenSSL::SSL::SSLContext.new
 #
@@ -379,8 +379,8 @@
 #     context.cert = cert
 #     context.key = key
 #
-# Then create an SSLServer with a TCP server socket and the context.  Use the
-# SSLServer like an ordinary TCP server.
+# Then create an OpenSSL::SSL::SSLServer with a TCP server socket and the
+# context.  Use the SSLServer like an ordinary TCP server.
 #
 #     require 'socket'
 #
@@ -401,12 +401,13 @@
 #
 # ### SSL client
 #
-# An SSL client is created with a TCP socket and the context. SSLSocket#connect
-# must be called to initiate the SSL handshake and start encryption.  A key and
-# certificate are not required for the client socket.
+# An SSL client is created with a TCP socket and the context.
+# OpenSSL::SSL::SSLSocket#connect must be called to initiate the SSL handshake
+# and start encryption.  A key and certificate are not required for the client
+# socket.
 #
-# Note that SSLSocket#close doesn't close the underlying socket by default. Set
-# SSLSocket#sync_close to true if you want.
+# Note that OpenSSL::SSL::SSLSocket#close doesn't close the underlying socket by
+# default. Set OpenSSL::SSL::SSLSocket#sync_close to true if you want.
 #
 #     require 'socket'
 #
@@ -440,8 +441,8 @@
 #     ssl_client.puts "hello server!"
 #     puts ssl_client.gets
 #
-# If the server certificate is invalid or `context.ca_file` is not set when
-# verifying peers an OpenSSL::SSL::SSLError will be raised.
+# If the server certificate is invalid or <code>context.ca_file</code> is not
+# set when verifying peers an OpenSSL::SSL::SSLError will be raised.
 #
 module OpenSSL
   # <!--
@@ -455,7 +456,7 @@ module OpenSSL
   #     OpenSSL::Digest("MD5")
   #     # => OpenSSL::Digest::MD5
   #
-  #     Digest("Foo")
+  #     OpenSSL::Digest("Foo")
   #     # => NameError: wrong constant name Foo
   #
   def self.Digest: (String name) -> singleton(Digest)
@@ -464,12 +465,13 @@ module OpenSSL
   #   rdoc-file=ext/openssl/ossl.c
   #   - OpenSSL.debug -> true | false
   # -->
+  # Returns whether Ruby/OpenSSL's debug mode is currently enabled.
   #
   def self.debug: () -> bool
 
   # <!--
   #   rdoc-file=ext/openssl/ossl.c
-  #   - OpenSSL.debug = boolean -> boolean
+  #   - OpenSSL.debug = boolean
   # -->
   # Turns on or off debug mode. With debug mode, all errors added to the OpenSSL
   # error queue will be printed to stderr.
@@ -480,10 +482,14 @@ module OpenSSL
   #   rdoc-file=ext/openssl/ossl.c
   #   - OpenSSL.errors -> [String...]
   # -->
-  # See any remaining errors held in queue.
+  # Returns any remaining errors held in the OpenSSL thread-local error queue and
+  # clears the queue. This should normally return an empty array.
   #
-  # Any errors you see here are probably due to a bug in Ruby's OpenSSL
-  # implementation.
+  # This is intended for debugging Ruby/OpenSSL. If you see any errors here, it
+  # likely indicates a bug in the extension. Please file an issue at
+  # https://github.com/ruby/openssl.
+  #
+  # For debugging your program, OpenSSL.debug= may be useful.
   #
   def self.errors: () -> Array[String]
 
@@ -491,12 +497,13 @@ module OpenSSL
   #   rdoc-file=ext/openssl/ossl.c
   #   - OpenSSL.fips_mode -> true | false
   # -->
+  # Returns whether the FIPS mode is currently enabled.
   #
   def self.fips_mode: () -> bool
 
   # <!--
   #   rdoc-file=ext/openssl/ossl.c
-  #   - OpenSSL.fips_mode = boolean -> boolean
+  #   - OpenSSL.fips_mode = boolean
   # -->
   # Turns FIPS mode on or off. Turning on FIPS mode will obviously only have an
   # effect for FIPS-capable installations of the OpenSSL library. Trying to do so
@@ -510,57 +517,74 @@ module OpenSSL
 
   # <!--
   #   rdoc-file=ext/openssl/ossl.c
-  #   - OpenSSL.fixed_length_secure_compare(string, string) -> boolean
+  #   - OpenSSL.fixed_length_secure_compare(string, string) -> true or false
   # -->
   # Constant time memory comparison for fixed length strings, such as results of
   # HMAC calculations.
   #
   # Returns `true` if the strings are identical, `false` if they are of the same
-  # length but not identical. If the length is different, `ArgumentError` is
-  # raised.
+  # length but not identical. If the length is different, ArgumentError is raised.
   #
   def self.fixed_length_secure_compare: (String, String) -> bool
 
   # <!--
   #   rdoc-file=ext/openssl/lib/openssl.rb
-  #   - OpenSSL.secure_compare(string, string) -> boolean
+  #   - OpenSSL.secure_compare(string, string) -> true or false
   # -->
   # Constant time memory comparison. Inputs are hashed using SHA-256 to mask the
   # length of the secret. Returns `true` if the strings are identical, `false`
   # otherwise.
   #
+  # This method is expensive due to the SHA-256 hashing. In most cases, where the
+  # input lengths are known to be equal or are not sensitive,
+  # OpenSSL.fixed_length_secure_compare should be used instead.
+  #
   def self.secure_compare: (String a, String b) -> bool
 
   # <!-- rdoc-file=ext/openssl/ossl.c -->
-  # Boolean indicating whether OpenSSL is FIPS-capable or not
+  # Boolean indicating whether the OpenSSL library is FIPS-capable or not. Always
+  # `true` for OpenSSL 3.0 and later.
+  #
+  # This is obsolete and will be removed in the future. See also
+  # OpenSSL.fips_mode.
   #
   OPENSSL_FIPS: bool
 
+  # <!-- rdoc-file=ext/openssl/ossl.c -->
+  # OpenSSL library version string currently used at runtime.
+  #
   OPENSSL_LIBRARY_VERSION: String
 
   # <!-- rdoc-file=ext/openssl/ossl.c -->
-  # Version of OpenSSL the ruby OpenSSL extension was built with
+  # OpenSSL library version string used to compile the Ruby/OpenSSL extension.
+  # This may differ from the version used at runtime.
   #
   OPENSSL_VERSION: String
 
   # <!-- rdoc-file=ext/openssl/ossl.c -->
-  # Version number of OpenSSL the ruby OpenSSL extension was built with (base 16).
-  # The formats are below.
+  # OpenSSL library version number used to compile the Ruby/OpenSSL extension.
+  # This may differ from the version used at runtime.
   #
-  # OpenSSL 3
-  # :   `0xMNN00PP0 (major minor 00 patch 0)`
+  # The version number is encoded into a single integer value. The number follows
+  # the format:
   #
-  # OpenSSL before 3
-  # :   `0xMNNFFPPS (major minor fix patch status)`
+  # OpenSSL 3.0.0 or later
+  # :   `0xMNN00PP0` (major minor 00 patch 0)
+  #
+  # OpenSSL 1.1.1 or earlier
+  # :   `0xMNNFFPPS` (major minor fix patch status)
   #
   # LibreSSL
-  # :   `0x20000000 (fixed value)`
+  # :   `0x20000000` (a fixed value)
   #
   #
   # See also the man page OPENSSL_VERSION_NUMBER(3).
   #
   OPENSSL_VERSION_NUMBER: Integer
 
+  # <!-- rdoc-file=ext/openssl/lib/openssl/version.rb -->
+  # The version string of Ruby/OpenSSL.
+  #
   VERSION: String
 
   # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
@@ -588,7 +612,8 @@ module OpenSSL
   # can only be determined using out-of-band information from the ASN.1 type
   # declaration. Since this information is normally known when encoding a type,
   # all sub-classes of ASN1Data offer an additional attribute *tagging* that
-  # allows to encode a value implicitly (`:IMPLICIT`) or explicitly (`:EXPLICIT`).
+  # allows to encode a value implicitly (<code>:IMPLICIT</code>) or explicitly
+  # (<code>:EXPLICIT</code>).
   #
   # ### Constructive
   #
@@ -616,18 +641,18 @@ module OpenSSL
   # When constructing an ASN1Data object the ASN.1 type definition may require
   # certain elements to be either implicitly or explicitly tagged. This can be
   # achieved by setting the *tagging* attribute manually for sub-classes of
-  # ASN1Data. Use the symbol `:IMPLICIT` for implicit tagging and `:EXPLICIT` if
-  # the element requires explicit tagging.
+  # ASN1Data. Use the symbol <code>:IMPLICIT</code> for implicit tagging and
+  # <code>:EXPLICIT</code> if the element requires explicit tagging.
   #
   # ## Possible values for *tag_class*
   #
   # It is possible to create arbitrary ASN1Data objects that also support a
   # PRIVATE or APPLICATION tag class. Possible values for the *tag_class*
   # attribute are:
-  # *   `:UNIVERSAL` (the default for untagged values)
-  # *   `:CONTEXT_SPECIFIC` (the default for tagged values)
-  # *   `:APPLICATION`
-  # *   `:PRIVATE`
+  # *   <code>:UNIVERSAL</code> (the default for untagged values)
+  # *   <code>:CONTEXT_SPECIFIC</code> (the default for tagged values)
+  # *   <code>:APPLICATION</code>
+  # *   <code>:PRIVATE</code>
   #
   # ## Tag constants
   #
@@ -660,7 +685,8 @@ module OpenSSL
   #
   # An Array that stores the name of a given tag number. These names are the same
   # as the name of the tag constant that is additionally defined, e.g.
-  # `UNIVERSAL_TAG_NAME[2] = "INTEGER"` and `OpenSSL::ASN1::INTEGER = 2`.
+  # <code>UNIVERSAL_TAG_NAME[2] = "INTEGER"</code> and
+  # <code>OpenSSL::ASN1::INTEGER = 2</code>.
   #
   # ## Example usage
   #
@@ -736,8 +762,8 @@ module OpenSSL
     #   - OpenSSL::ASN1.decode(der) -> ASN1Data
     # -->
     # Decodes a BER- or DER-encoded value and creates an ASN1Data instance. *der*
-    # may be a String or any object that features a `.to_der` method transforming it
-    # into a BER-/DER-encoded String+
+    # may be a String or any object that features a <code>.to_der</code> method
+    # transforming it into a BER-/DER-encoded String+
     #
     # ## Example
     #     der = File.binread('asn1data')
@@ -868,7 +894,7 @@ module OpenSSL
     #
     # An implicitly 1-tagged INTEGER value will be parsed as an ASN1Data with
     # *   *tag* equal to 1
-    # *   *tag_class* equal to `:CONTEXT_SPECIFIC`
+    # *   *tag_class* equal to <code>:CONTEXT_SPECIFIC</code>
     # *   *value* equal to a String that carries the raw encoding of the INTEGER.
     # This implies that a subsequent decoding step is required to completely decode
     # implicitly tagged values.
@@ -877,7 +903,7 @@ module OpenSSL
     #
     # An explicitly 1-tagged INTEGER value will be parsed as an ASN1Data with
     # *   *tag* equal to 1
-    # *   *tag_class* equal to `:CONTEXT_SPECIFIC`
+    # *   *tag_class* equal to <code>:CONTEXT_SPECIFIC</code>
     # *   *value* equal to an Array with one single element, an instance of
     #     OpenSSL::ASN1::Integer, i.e. the inner element is the non-tagged primitive
     #     value, and the tagging is represented in the outer ASN1Data
@@ -931,7 +957,7 @@ module OpenSSL
     #     puts int2.value # => 1
     #
     class ASN1Data
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # Never `nil`. A boolean value indicating whether the encoding uses indefinite
       # length (in the case of parsing) or whether an indefinite length form shall be
       # used (in the encoding case). In DER, every value uses definite length form.
@@ -948,7 +974,7 @@ module OpenSSL
       #
       def indefinite_length: () -> bool
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # Never `nil`. A boolean value indicating whether the encoding uses indefinite
       # length (in the case of parsing) or whether an indefinite length form shall be
       # used (in the encoding case). In DER, every value uses definite length form.
@@ -965,7 +991,7 @@ module OpenSSL
       #
       def indefinite_length=: [U] (boolish) -> U
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # Never `nil`. A boolean value indicating whether the encoding uses indefinite
       # length (in the case of parsing) or whether an indefinite length form shall be
       # used (in the encoding case). In DER, every value uses definite length form.
@@ -982,7 +1008,7 @@ module OpenSSL
       #
       alias infinite_length indefinite_length
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # Never `nil`. A boolean value indicating whether the encoding uses indefinite
       # length (in the case of parsing) or whether an indefinite length form shall be
       # used (in the encoding case). In DER, every value uses definite length form.
@@ -999,24 +1025,24 @@ module OpenSSL
       #
       alias infinite_length= indefinite_length=
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # An Integer representing the tag number of this ASN1Data. Never `nil`.
       #
       def tag: () -> bn
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # An Integer representing the tag number of this ASN1Data. Never `nil`.
       #
       def tag=: (::Integer) -> ::Integer
               | (BN) -> BN
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # A Symbol representing the tag class of this ASN1Data. Never `nil`. See
       # ASN1Data for possible values.
       #
       def tag_class: () -> tag_class
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # A Symbol representing the tag class of this ASN1Data. Never `nil`. See
       # ASN1Data for possible values.
       #
@@ -1033,13 +1059,13 @@ module OpenSSL
       #
       def to_der: () -> String
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # Carries the value of a ASN.1 type. Please confer Constructive and Primitive
       # for the mappings between ASN.1 data types and Ruby classes.
       #
       def value: () -> untyped
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/asn1.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # Carries the value of a ASN.1 type. Please confer Constructive and Primitive
       # for the mappings between ASN.1 data types and Ruby classes.
       #
@@ -1048,7 +1074,7 @@ module OpenSSL
       private
 
       # <!--
-      #   rdoc-file=ext/openssl/lib/openssl/asn1.rb
+      #   rdoc-file=ext/openssl/ossl_asn1.c
       #   - OpenSSL::ASN1::ASN1Data.new(value, tag, tag_class) => ASN1Data
       # -->
       # *value*: Please have a look at Constructive and Primitive to see how Ruby
@@ -1120,7 +1146,7 @@ module OpenSSL
       include Enumerable[ASN1Data]
 
       # <!--
-      #   rdoc-file=ext/openssl/lib/openssl/asn1.rb
+      #   rdoc-file=ext/openssl/ossl_asn1.c
       #   - asn1_ary.each { |asn1| block } => asn1_ary
       # -->
       # Calls the given block once for each element in self, passing that element as
@@ -1135,15 +1161,17 @@ module OpenSSL
 
       # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # May be used as a hint for encoding a value either implicitly or explicitly by
-      # setting it either to `:IMPLICIT` or to `:EXPLICIT`. *tagging* is not set when
-      # a ASN.1 structure is parsed using OpenSSL::ASN1.decode.
+      # setting it either to <code>:IMPLICIT</code> or to <code>:EXPLICIT</code>.
+      # *tagging* is not set when a ASN.1 structure is parsed using
+      # OpenSSL::ASN1.decode.
       #
       def tagging: () -> tagging?
 
       # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # May be used as a hint for encoding a value either implicitly or explicitly by
-      # setting it either to `:IMPLICIT` or to `:EXPLICIT`. *tagging* is not set when
-      # a ASN.1 structure is parsed using OpenSSL::ASN1.decode.
+      # setting it either to <code>:IMPLICIT</code> or to <code>:EXPLICIT</code>.
+      # *tagging* is not set when a ASN.1 structure is parsed using
+      # OpenSSL::ASN1.decode.
       #
       def tagging=: (tagging) -> tagging
 
@@ -1169,9 +1197,10 @@ module OpenSSL
       # *tagging*: may be used as an encoding hint to encode a value either explicitly
       # or implicitly, see ASN1 for possible values.
       #
-      # *tag_class*: if *tag* and *tagging* are `nil` then this is set to `:UNIVERSAL`
-      # by default. If either *tag* or *tagging* are set then `:CONTEXT_SPECIFIC` is
-      # used as the default. For possible values please cf. ASN1.
+      # *tag_class*: if *tag* and *tagging* are `nil` then this is set to
+      # <code>:UNIVERSAL</code> by default. If either *tag* or *tagging* are set then
+      # <code>:CONTEXT_SPECIFIC</code> is used as the default. For possible values
+      # please cf. ASN1.
       #
       # ## Example
       #     int = OpenSSL::ASN1::Integer.new(42)
@@ -1384,15 +1413,17 @@ module OpenSSL
     class Primitive < OpenSSL::ASN1::ASN1Data
       # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # May be used as a hint for encoding a value either implicitly or explicitly by
-      # setting it either to `:IMPLICIT` or to `:EXPLICIT`. *tagging* is not set when
-      # a ASN.1 structure is parsed using OpenSSL::ASN1.decode.
+      # setting it either to <code>:IMPLICIT</code> or to <code>:EXPLICIT</code>.
+      # *tagging* is not set when a ASN.1 structure is parsed using
+      # OpenSSL::ASN1.decode.
       #
       def tagging: () -> tagging?
 
       # <!-- rdoc-file=ext/openssl/ossl_asn1.c -->
       # May be used as a hint for encoding a value either implicitly or explicitly by
-      # setting it either to `:IMPLICIT` or to `:EXPLICIT`. *tagging* is not set when
-      # a ASN.1 structure is parsed using OpenSSL::ASN1.decode.
+      # setting it either to <code>:IMPLICIT</code> or to <code>:EXPLICIT</code>.
+      # *tagging* is not set when a ASN.1 structure is parsed using
+      # OpenSSL::ASN1.decode.
       #
       def tagging=: (tagging) -> tagging
 
@@ -1418,9 +1449,10 @@ module OpenSSL
       # *tagging*: may be used as an encoding hint to encode a value either explicitly
       # or implicitly, see ASN1 for possible values.
       #
-      # *tag_class*: if *tag* and *tagging* are `nil` then this is set to `:UNIVERSAL`
-      # by default. If either *tag* or *tagging* are set then `:CONTEXT_SPECIFIC` is
-      # used as the default. For possible values please cf. ASN1.
+      # *tag_class*: if *tag* and *tagging* are `nil` then this is set to
+      # <code>:UNIVERSAL</code> by default. If either *tag* or *tagging* are set then
+      # <code>:CONTEXT_SPECIFIC</code> is used as the default. For possible values
+      # please cf. ASN1.
       #
       # ## Example
       #     int = OpenSSL::ASN1::Integer.new(42)
@@ -1487,7 +1519,7 @@ module OpenSSL
     # -->
     # Generates a random prime number of bit length *bits*. If *safe* is set to
     # `true`, generates a safe prime. If *add* is specified, generates a prime that
-    # fulfills condition `p % add = rem`.
+    # fulfills condition <code>p % add = rem</code>.
     #
     # ### Parameters
     # *   *bits* - integer
@@ -1656,8 +1688,8 @@ module OpenSSL
     #   rdoc-file=ext/openssl/ossl_bn.c
     #   - bn.eql?(obj) => true or false
     # -->
-    # Returns `true` only if *obj* is a `OpenSSL::BN` with the same value as *bn*.
-    # Contrast this with OpenSSL::BN#==, which performs type conversions.
+    # Returns `true` only if *obj* is a <code>OpenSSL::BN</code> with the same value
+    # as *bn*. Contrast this with OpenSSL::BN#==, which performs type conversions.
     #
     def eql?: (untyped other) -> bool
 
@@ -1778,7 +1810,8 @@ module OpenSSL
     # -->
     # Performs a Miller-Rabin probabilistic primality test for `bn`.
     #
-    # **`checks` parameter is deprecated in version 3.0.** It has no effect.
+    # <strong>`checks` parameter is deprecated in version 3.0.</strong> It has no
+    # effect.
     #
     def prime?: (?int checks) -> bool
 
@@ -1790,7 +1823,7 @@ module OpenSSL
     # -->
     # Performs a Miller-Rabin probabilistic primality test for `bn`.
     #
-    # **Deprecated in version 3.0.** Use #prime? instead.
+    # <strong>Deprecated in version 3.0.</strong> Use #prime? instead.
     #
     # `checks` and `trial_div` parameters no longer have any effect.
     #
@@ -1940,8 +1973,8 @@ module OpenSSL
     #   rdoc-file=ext/openssl/lib/openssl/buffering.rb
     #   - <<(s)
     # -->
-    # Writes *s* to the stream.  *s* will be converted to a String using `.to_s`
-    # method.
+    # Writes *s* to the stream.  *s* will be converted to a String using
+    # <code>.to_s</code> method.
     #
     def <<: (String s) -> self
 
@@ -2103,8 +2136,8 @@ module OpenSSL
     #
     # By specifying a keyword argument *exception* to `false`, you can indicate that
     # read_nonblock should not raise an IO::Wait*able exception, but return the
-    # symbol `:wait_writable` or `:wait_readable` instead. At EOF, it will return
-    # `nil` instead of raising EOFError.
+    # symbol <code>:wait_writable</code> or <code>:wait_readable</code> instead. At
+    # EOF, it will return `nil` instead of raising EOFError.
     #
     def read_nonblock: (Integer maxlen, ?String buf, ?exception: true) -> String
                      | (Integer maxlen, ?String buf, exception: false) -> (String | :wait_writable | :wait_readable | nil)
@@ -2181,7 +2214,8 @@ module OpenSSL
     #   - write(*s)
     # -->
     # Writes *s* to the stream.  If the argument is not a String it will be
-    # converted using `.to_s` method.  Returns the number of bytes written.
+    # converted using <code>.to_s</code> method.  Returns the number of bytes
+    # written.
     #
     def write: (*_ToS s) -> Integer
 
@@ -2223,7 +2257,7 @@ module OpenSSL
     #
     # By specifying a keyword argument *exception* to `false`, you can indicate that
     # write_nonblock should not raise an IO::Wait*able exception, but return the
-    # symbol `:wait_writable` or `:wait_readable` instead.
+    # symbol <code>:wait_writable</code> or <code>:wait_readable</code> instead.
     #
     def write_nonblock: (_ToS s, ?exception: true) -> Integer
                       | (_ToS s, exception: false) -> (Integer | :wait_writable | :wait_readable | nil)
@@ -2428,24 +2462,28 @@ module OpenSSL
   # prevents malicious modifications of the ciphertext that could otherwise be
   # exploited to modify ciphertexts in ways beneficial to potential attackers.
   #
-  # An associated data is used where there is additional information, such as
-  # headers or some metadata, that must be also authenticated but not necessarily
-  # need to be encrypted. If no associated data is needed for encryption and later
-  # decryption, the OpenSSL library still requires a value to be set - "" may be
-  # used in case none is available.
+  # Associated data, also called additional authenticated data (AAD), is
+  # optionally used where there is additional information, such as headers or some
+  # metadata, that must be also authenticated but not necessarily need to be
+  # encrypted.
   #
   # An example using the GCM (Galois/Counter Mode). You have 16 bytes *key*, 12
   # bytes (96 bits) *nonce* and the associated data *auth_data*. Be sure not to
   # reuse the *key* and *nonce* pair. Reusing an nonce ruins the security
   # guarantees of GCM mode.
   #
+  #     key = OpenSSL::Random.random_bytes(16)
+  #     nonce = OpenSSL::Random.random_bytes(12)
+  #     auth_data = "authenticated but unencrypted data"
+  #     data = "encrypted data"
+  #
   #     cipher = OpenSSL::Cipher.new('aes-128-gcm').encrypt
   #     cipher.key = key
   #     cipher.iv = nonce
   #     cipher.auth_data = auth_data
   #
   #     encrypted = cipher.update(data) + cipher.final
-  #     tag = cipher.auth_tag # produces 16 bytes tag by default
+  #     tag = cipher.auth_tag(16)
   #
   # Now you are the receiver. You know the *key* and have received *nonce*,
   # *auth_data*, *encrypted* and *tag* through an untrusted network. Note that GCM
@@ -2458,13 +2496,17 @@ module OpenSSL
   #     decipher = OpenSSL::Cipher.new('aes-128-gcm').decrypt
   #     decipher.key = key
   #     decipher.iv = nonce
-  #     decipher.auth_tag = tag
+  #     decipher.auth_tag = tag # could be called at any time before #final
   #     decipher.auth_data = auth_data
   #
   #     decrypted = decipher.update(encrypted) + decipher.final
   #
   #     puts data == decrypted #=> true
   #
+  # Note that other AEAD ciphers may require additional steps, such as setting the
+  # expected tag length (#auth_tag_len=) or the total data length (#ccm_data_len=)
+  # in advance. Make sure to read the relevant man page for details.
+  #
   class Cipher
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
@@ -2476,21 +2518,22 @@ module OpenSSL
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.auth_data = string -> string
-    # -->
-    # Sets the cipher's additional authenticated data. This field must be set when
-    # using AEAD cipher modes such as GCM or CCM. If no associated data shall be
-    # used, this method must **still** be called with a value of "". The contents of
-    # this field should be non-sensitive data which will be added to the ciphertext
-    # to generate the authentication tag which validates the contents of the
-    # ciphertext.
-    #
-    # The AAD must be set prior to encryption or decryption. In encryption mode, it
-    # must be set after calling Cipher#encrypt and setting Cipher#key= and
-    # Cipher#iv=. When decrypting, the authenticated data must be set after key, iv
-    # and especially **after** the authentication tag has been set. I.e. set it only
-    # after calling Cipher#decrypt, Cipher#key=, Cipher#iv= and Cipher#auth_tag=
-    # first.
+    #   - cipher.auth_data = string
+    # -->
+    # Sets additional authenticated data (AAD), also called associated data, for
+    # this Cipher. This method is available for AEAD ciphers.
+    #
+    # The contents of this field should be non-sensitive data which will be added to
+    # the ciphertext to generate the authentication tag which validates the contents
+    # of the ciphertext.
+    #
+    # This method must be called after #key= and #iv= have been set, but before
+    # starting actual encryption or decryption with #update. In some cipher modes,
+    # #auth_tag_len= and #ccm_data_len= may also need to be called before this
+    # method.
+    #
+    # See also the "AEAD Interface" section of the man page EVP_EncryptInit(3). This
+    # method internally calls EVP_CipherUpdate() with the output buffer set to NULL.
     #
     def auth_data=: (String) -> String
 
@@ -2498,42 +2541,54 @@ module OpenSSL
     #   rdoc-file=ext/openssl/ossl_cipher.c
     #   - cipher.auth_tag(tag_len = 16) -> String
     # -->
-    # Gets the authentication tag generated by Authenticated Encryption Cipher modes
-    # (GCM for example). This tag may be stored along with the ciphertext, then set
-    # on the decryption cipher to authenticate the contents of the ciphertext
-    # against changes. If the optional integer parameter *tag_len* is given, the
-    # returned tag will be *tag_len* bytes long. If the parameter is omitted, the
-    # default length of 16 bytes or the length previously set by #auth_tag_len= will
-    # be used. For maximum security, the longest possible should be chosen.
+    # Gets the generated authentication tag. This method is available for AEAD
+    # ciphers, and should be called after encryption has been finalized by calling
+    # #final.
     #
-    # The tag may only be retrieved after calling Cipher#final.
+    # The returned tag will be *tag_len* bytes long. Some cipher modes require the
+    # desired length in advance using a separate call to #auth_tag_len=, before
+    # starting encryption.
+    #
+    # See also the "AEAD Interface" section of the man page EVP_EncryptInit(3). This
+    # method internally calls EVP_CIPHER_CTX_ctrl() with EVP_CTRL_AEAD_GET_TAG.
     #
     def auth_tag: (?Integer tag_len) -> String
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.auth_tag = string -> string
+    #   - cipher.auth_tag = string
     # -->
-    # Sets the authentication tag to verify the integrity of the ciphertext. This
-    # can be called only when the cipher supports AE. The tag must be set after
-    # calling Cipher#decrypt, Cipher#key= and Cipher#iv=, but before calling
-    # Cipher#final. After all decryption is performed, the tag is verified
-    # automatically in the call to Cipher#final.
+    # Sets the authentication tag to verify the integrity of the ciphertext.
+    #
+    # The authentication tag must be set before #final is called. The tag is
+    # verified during the #final call.
     #
-    # For OCB mode, the tag length must be supplied with #auth_tag_len= beforehand.
+    # Note that, for CCM mode and OCB mode, the expected length of the tag must be
+    # set before starting decryption by a separate call to #auth_tag_len=. The
+    # content of the tag can be provided at any time before #final is called.
+    #
+    # **NOTE**: The caller must ensure that the String passed to this method has the
+    # desired length. Some cipher modes support variable tag lengths, and this
+    # method may accept a truncated tag without raising an exception.
+    #
+    # See also the "AEAD Interface" section of the man page EVP_EncryptInit(3). This
+    # method internally calls EVP_CIPHER_CTX_ctrl() with EVP_CTRL_AEAD_SET_TAG.
     #
     def auth_tag=: (String) -> String
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.auth_tag_len = Integer -> Integer
+    #   - cipher.auth_tag_len = integer
     # -->
-    # Sets the length of the authentication tag to be generated or to be given for
-    # AEAD ciphers that requires it as in input parameter. Note that not all AEAD
-    # ciphers support this method.
+    # Sets the length of the expected authentication tag for this Cipher. This
+    # method is available for some of AEAD ciphers that require the length to be set
+    # before starting encryption or decryption, such as CCM mode or OCB mode.
     #
-    # In OCB mode, the length must be supplied both when encrypting and when
-    # decrypting, and must be before specifying an IV.
+    # For CCM mode and OCB mode, the tag length must be set before #iv= is set.
+    #
+    # See also the "AEAD Interface" section of the man page EVP_EncryptInit(3). This
+    # method internally calls EVP_CIPHER_CTX_ctrl() with EVP_CTRL_AEAD_SET_TAG and a
+    # NULL buffer.
     #
     def auth_tag_len=: (Integer) -> Integer
 
@@ -2541,7 +2596,7 @@ module OpenSSL
     #   rdoc-file=ext/openssl/ossl_cipher.c
     #   - cipher.authenticated? -> true | false
     # -->
-    # Indicated whether this Cipher instance uses an Authenticated Encryption mode.
+    # Indicates whether this Cipher instance uses an AEAD mode.
     #
     def authenticated?: () -> bool
 
@@ -2559,11 +2614,9 @@ module OpenSSL
     # -->
     # Initializes the Cipher for decryption.
     #
-    # Make sure to call Cipher#encrypt or Cipher#decrypt before using any of the
-    # following methods:
+    # Make sure to call either #encrypt or #decrypt before using the Cipher for any
+    # operation or setting any parameters.
     #
-    #     #key=, #iv=, #random_key, #random_iv, #pkcs5_keyivgen
-    # :
     # Internally calls EVP_CipherInit_ex(ctx, NULL, NULL, NULL, NULL, 0).
     #
     def decrypt: () -> self
@@ -2574,11 +2627,9 @@ module OpenSSL
     # -->
     # Initializes the Cipher for encryption.
     #
-    # Make sure to call Cipher#encrypt or Cipher#decrypt before using any of the
-    # following methods:
+    # Make sure to call either #encrypt or #decrypt before using the Cipher for any
+    # operation or setting any parameters.
     #
-    #     #key=, #iv=, #random_key, #random_iv, #pkcs5_keyivgen
-    # :
     # Internally calls EVP_CipherInit_ex(ctx, NULL, NULL, NULL, NULL, 1).
     #
     def encrypt: () -> self
@@ -2588,28 +2639,37 @@ module OpenSSL
     #   - cipher.final -> string
     # -->
     # Returns the remaining data held in the cipher object. Further calls to
-    # Cipher#update or Cipher#final will return garbage. This call should always be
-    # made as the last call of an encryption or decryption operation, after having
-    # fed the entire plaintext or ciphertext to the Cipher instance.
+    # Cipher#update or Cipher#final are invalid. This call should always be made as
+    # the last call of an encryption or decryption operation, after having fed the
+    # entire plaintext or ciphertext to the Cipher instance.
+    #
+    # When encrypting using an AEAD cipher, the authentication tag can be retrieved
+    # by #auth_tag after #final has been called.
     #
-    # If an authenticated cipher was used, a CipherError is raised if the tag could
-    # not be authenticated successfully. Only call this method after setting the
-    # authentication tag and passing the entire contents of the ciphertext into the
-    # cipher.
+    # When decrypting using an AEAD cipher, this method will verify the integrity of
+    # the ciphertext and the associated data with the authentication tag, which must
+    # be set by #auth_tag= prior to calling this method. If the verification fails,
+    # CipherError will be raised.
     #
     def final: () -> String
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.iv = string -> string
+    #   - cipher.iv = string
     # -->
     # Sets the cipher IV. Please note that since you should never be using ECB mode,
     # an IV is always explicitly required and should be set prior to encryption. The
-    # IV itself can be safely transmitted in public, but it should be unpredictable
-    # to prevent certain kinds of attacks. You may use Cipher#random_iv to create a
-    # secure random IV.
+    # IV itself can be safely transmitted in public.
     #
-    # Only call this method after calling Cipher#encrypt or Cipher#decrypt.
+    # This method expects the String to have the length equal to #iv_len. To use a
+    # different IV length with an AEAD cipher, #iv_len= must be set prior to calling
+    # this method.
+    #
+    # **NOTE**: In OpenSSL API conventions, the IV value may correspond to the
+    # "nonce" instead in some cipher modes. Refer to the OpenSSL man pages for
+    # details.
+    #
+    # See also the man page EVP_CipherInit_ex(3).
     #
     def iv=: (String iv) -> String
 
@@ -2623,17 +2683,20 @@ module OpenSSL
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.iv_len = integer -> integer
+    #   - cipher.iv_len = integer
     # -->
-    # Sets the IV/nonce length of the Cipher. Normally block ciphers don't allow
-    # changing the IV length, but some make use of IV for 'nonce'. You may need this
-    # for interoperability with other applications.
+    # Sets the IV/nonce length for this Cipher. This method is available for AEAD
+    # ciphers that support variable IV lengths. This method can be called if a
+    # different IV length than OpenSSL's default is desired, prior to calling #iv=.
+    #
+    # See also the "AEAD Interface" section of the man page EVP_EncryptInit(3). This
+    # method internally calls EVP_CIPHER_CTX_ctrl() with EVP_CTRL_AEAD_SET_IVLEN.
     #
     def iv_len=: (Integer) -> Integer
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.key = string -> string
+    #   - cipher.key = string
     # -->
     # Sets the cipher key. To generate a key, you should either use a secure random
     # byte string or, if the key is to be derived from a password, you should rely
@@ -2642,6 +2705,8 @@ module OpenSSL
     #
     # Only call this method after calling Cipher#encrypt or Cipher#decrypt.
     #
+    # See also the man page EVP_CipherInit_ex(3).
+    #
     def key=: (String key) -> String
 
     # <!--
@@ -2654,7 +2719,7 @@ module OpenSSL
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.key_len = integer -> integer
+    #   - cipher.key_len = integer
     # -->
     # Sets the key length of the cipher.  If the cipher is a fixed length cipher
     # then attempting to set the key length to any value other than the fixed value
@@ -2678,7 +2743,7 @@ module OpenSSL
 
     # <!--
     #   rdoc-file=ext/openssl/ossl_cipher.c
-    #   - cipher.padding = integer -> integer
+    #   - cipher.padding = 1 or 0
     # -->
     # Enables or disables padding. By default encryption operations are padded using
     # standard block padding and the padding is checked and removed when decrypting.
@@ -2696,19 +2761,16 @@ module OpenSSL
     # -->
     # Generates and sets the key/IV based on a password.
     #
-    # **WARNING**: This method is only PKCS5 v1.5 compliant when using RC2, RC4-40,
-    # or DES with MD5 or SHA1. Using anything else (like AES) will generate the
-    # key/iv using an OpenSSL specific method. This method is deprecated and should
-    # no longer be used. Use a PKCS5 v2 key generation method from OpenSSL::PKCS5
-    # instead.
+    # **WARNING**: This method is deprecated and should not be used. This method
+    # corresponds to EVP_BytesToKey(), a non-standard OpenSSL extension of the
+    # legacy PKCS #5 v1.5 key derivation function. See OpenSSL::KDF for other
+    # options to derive keys from passwords.
     #
     # ### Parameters
     # *   *salt* must be an 8 byte string if provided.
     # *   *iterations* is an integer with a default of 2048.
     # *   *digest* is a Digest object that defaults to 'MD5'
     #
-    # A minimum of 1000 iterations is recommended.
-    #
     def pkcs5_keyivgen: (String pass, ?String salt, ?Integer iterations, ?String digest) -> void
 
     # <!--
@@ -2755,6 +2817,9 @@ module OpenSSL
     # If *buffer* is given, the encryption/decryption result will be written to it.
     # *buffer* will be resized automatically.
     #
+    # **NOTE**: When decrypting using an AEAD cipher, the integrity of the output is
+    # not verified until #final has been called.
+    #
     def update: (String data, ?String buffer) -> String
 
     private
@@ -2863,7 +2928,7 @@ module OpenSSL
   # configuration. See the value of OpenSSL::Config::DEFAULT_CONFIG_FILE for the
   # location of the file for your host.
   #
-  # See also http://www.openssl.org/docs/apps/config.html
+  # See also https://docs.openssl.org/master/man5/config/
   #
   class Config
     include Enumerable[[ String, String, String ]]
@@ -3910,7 +3975,7 @@ module OpenSSL
   # short-circuits on evaluation, and is therefore vulnerable to timing attacks.
   # The proper way is to use a method that always takes the same amount of time
   # when comparing two values, thus not leaking any information to potential
-  # attackers. To do this, use `OpenSSL.fixed_length_secure_compare`.
+  # attackers. To do this, use <code>OpenSSL.fixed_length_secure_compare</code>.
   #
   module KDF
     # <!--
@@ -3933,8 +3998,8 @@ module OpenSSL
     # :   The context and application specific information.
     #
     # *length*
-    # :   The output length in octets. Must be <= `255 * HashLen`, where HashLen is
-    #     the length of the hash function output in octets.
+    # :   The output length in octets. Must be <= <code>255 * HashLen</code>, where
+    #     HashLen is the length of the hash function output in octets.
     #
     # *hash*
     # :   The hash function.
@@ -4794,8 +4859,8 @@ module OpenSSL
       #
       #
       # For most responses, clients can check *result* > 0.  If a responder doesn't
-      # handle nonces `result.nonzero?` may be necessary.  A result of `0` is always
-      # an error.
+      # handle nonces <code>result.nonzero?</code> may be necessary.  A result of `0`
+      # is always an error.
       #
       def check_nonce: (Response response) -> (-1 | 0 | 1 | 2 | 3)
 
@@ -5042,7 +5107,11 @@ module OpenSSL
   end
 
   # <!-- rdoc-file=ext/openssl/ossl.c -->
-  # Generic error, common for all classes under OpenSSL module
+  # Generic error class for OpenSSL. All error classes in this library inherit
+  # from this class.
+  #
+  # This class indicates that an error was reported by the underlying OpenSSL
+  # library.
   #
   class OpenSSLError < StandardError
   end
@@ -5147,7 +5216,8 @@ module OpenSSL
     # -->
     # Creates a PKCS #7 enveloped-data structure.
     #
-    # Before version 3.3.0, `cipher` was optional and defaulted to `"RC2-40-CBC"`.
+    # Before version 3.3.0, `cipher` was optional and defaulted to
+    # <code>"RC2-40-CBC"</code>.
     #
     # See also the man page PKCS7_encrypt(3).
     #
@@ -5619,8 +5689,8 @@ module OpenSSL
       # result of DH#public_key), then this method needs to be called first in order
       # to generate the per-session keys before performing the actual key exchange.
       #
-      # **Deprecated in version 3.0**. This method is incompatible with OpenSSL 3.0.0
-      # or later.
+      # <strong>Deprecated in version 3.0</strong>. This method is incompatible with
+      # OpenSSL 3.0.0 or later.
       #
       # See also OpenSSL::PKey.generate_key.
       #
@@ -5642,11 +5712,12 @@ module OpenSSL
       def p: () -> BN
 
       # <!--
-      #   rdoc-file=ext/openssl/ossl_pkey_dh.c
+      #   rdoc-file=ext/openssl/lib/openssl/pkey.rb
       #   - dh.params -> hash
       # -->
-      # Stores all parameters of key to the hash INSECURE: PRIVATE INFORMATIONS CAN
-      # LEAK OUT!!! Don't use :-)) (I's up to you)
+      # Stores all parameters of key to a Hash.
+      #
+      # The hash has keys 'p', 'q', 'g', 'pub_key', and 'priv_key'.
       #
       def params: () -> Hash[String, BN?]
 
@@ -5798,7 +5869,8 @@ module OpenSSL
       #
       # If called without arguments, an empty instance without any parameter or key
       # components is created. Use #set_pqg to manually set the parameters afterwards
-      # (and optionally #set_key to set private and public key components).
+      # (and optionally #set_key to set private and public key components). This form
+      # is not compatible with OpenSSL 3.0 or later.
       #
       # If a String is given, tries to parse it as a DER- or PEM- encoded parameters.
       # See also OpenSSL::PKey.read which can parse keys of any kinds.
@@ -5817,14 +5889,15 @@ module OpenSSL
       #
       # Examples:
       #     # Creating an instance from scratch
-      #     # Note that this is deprecated and will not work on OpenSSL 3.0 or later.
+      #     # Note that this is deprecated and will result in ArgumentError when
+      #     # using OpenSSL 3.0 or later.
       #     dh = OpenSSL::PKey::DH.new
       #     dh.set_pqg(bn_p, nil, bn_g)
       #
       #     # Generating a parameters and a key pair
       #     dh = OpenSSL::PKey::DH.new(2048) # An alias of OpenSSL::PKey::DH.generate(2048)
       #
-      #     # Reading DH parameters
+      #     # Reading DH parameters from a PEM-encoded string
       #     dh_params = OpenSSL::PKey::DH.new(File.read('parameters.pem')) # loads parameters only
       #     dh = OpenSSL::PKey.generate_key(dh_params) # generates a key pair
       #
@@ -5922,8 +5995,8 @@ module OpenSSL
       #     will not be available on FIPS-compliant systems.
       #
       #
-      # **This method is kept for compatibility.** This should only be used when the
-      # traditional, non-standard OpenSSL format is required.
+      # <strong>This method is kept for compatibility.</strong> This should only be
+      # used when the traditional, non-standard OpenSSL format is required.
       #
       # Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
       # (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
@@ -5936,11 +6009,12 @@ module OpenSSL
       def p: () -> BN
 
       # <!--
-      #   rdoc-file=ext/openssl/ossl_pkey_dsa.c
+      #   rdoc-file=ext/openssl/lib/openssl/pkey.rb
       #   - dsa.params -> hash
       # -->
-      # Stores all parameters of key to the hash INSECURE: PRIVATE INFORMATIONS CAN
-      # LEAK OUT!!! Don't use :-)) (I's up to you)
+      # Stores all parameters of key to a Hash.
+      #
+      # The hash has keys 'p', 'q', 'g', 'pub_key', and 'priv_key'.
       #
       def params: () -> Hash[String, BN?]
 
@@ -6007,8 +6081,8 @@ module OpenSSL
       # to be an already-computed message digest of the original input data. The
       # signature is issued using the private key of this DSA instance.
       #
-      # **Deprecated in version 3.0**. Consider using PKey::PKey#sign_raw and
-      # PKey::PKey#verify_raw instead.
+      # <strong>Deprecated in version 3.0</strong>. Consider using PKey::PKey#sign_raw
+      # and PKey::PKey#verify_raw instead.
       #
       # `string`
       # :   A message digest of the original input data to be signed.
@@ -6036,8 +6110,8 @@ module OpenSSL
       # Verifies whether the signature is valid given the message digest input. It
       # does so by validating `sig` using the public key of this DSA instance.
       #
-      # **Deprecated in version 3.0**. Consider using PKey::PKey#sign_raw and
-      # PKey::PKey#verify_raw instead.
+      # <strong>Deprecated in version 3.0</strong>. Consider using PKey::PKey#sign_raw
+      # and PKey::PKey#verify_raw instead.
       #
       # `digest`
       # :   A message digest of the original input data to be signed.
@@ -6055,8 +6129,8 @@ module OpenSSL
       #
       # See #to_pem for details.
       #
-      # **This method is kept for compatibility.** This should only be used when the
-      # traditional, non-standard OpenSSL format is required.
+      # <strong>This method is kept for compatibility.</strong> This should only be
+      # used when the traditional, non-standard OpenSSL format is required.
       #
       # Consider using #public_to_der or #private_to_der instead.
       #
@@ -6108,8 +6182,8 @@ module OpenSSL
       #     will not be available on FIPS-compliant systems.
       #
       #
-      # **This method is kept for compatibility.** This should only be used when the
-      # traditional, non-standard OpenSSL format is required.
+      # <strong>This method is kept for compatibility.</strong> This should only be
+      # used when the traditional, non-standard OpenSSL format is required.
       #
       # Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
       # (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
@@ -6162,8 +6236,8 @@ module OpenSSL
       #     will not be available on FIPS-compliant systems.
       #
       #
-      # **This method is kept for compatibility.** This should only be used when the
-      # traditional, non-standard OpenSSL format is required.
+      # <strong>This method is kept for compatibility.</strong> This should only be
+      # used when the traditional, non-standard OpenSSL format is required.
       #
       # Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
       # (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
@@ -6190,7 +6264,8 @@ module OpenSSL
       # Creates a new DSA instance by reading an existing key from *string*.
       #
       # If called without arguments, creates a new instance with no key components
-      # set. They can be set individually by #set_pqg and #set_key.
+      # set. They can be set individually by #set_pqg and #set_key. This form is not
+      # compatible with OpenSSL 3.0 or later.
       #
       # If called with a String, tries to parse as DER or PEM encoding of a DSA key.
       # See also OpenSSL::PKey.read which can parse keys of any kinds.
@@ -6301,8 +6376,8 @@ module OpenSSL
       #   rdoc-file=ext/openssl/lib/openssl/pkey.rb
       #   - key.dsa_sign_asn1(data) -> String
       # -->
-      # **Deprecated in version 3.0**. Consider using PKey::PKey#sign_raw and
-      # PKey::PKey#verify_raw instead.
+      # <strong>Deprecated in version 3.0</strong>. Consider using PKey::PKey#sign_raw
+      # and PKey::PKey#verify_raw instead.
       #
       def dsa_sign_asn1: (String digest) -> String
 
@@ -6310,8 +6385,8 @@ module OpenSSL
       #   rdoc-file=ext/openssl/lib/openssl/pkey.rb
       #   - key.dsa_verify_asn1(data, sig) -> true | false
       # -->
-      # **Deprecated in version 3.0**. Consider using PKey::PKey#sign_raw and
-      # PKey::PKey#verify_raw instead.
+      # <strong>Deprecated in version 3.0</strong>. Consider using PKey::PKey#sign_raw
+      # and PKey::PKey#verify_raw instead.
       #
       def dsa_verify_asn1: (String digest, String signature) -> bool
 
@@ -6365,8 +6440,8 @@ module OpenSSL
       #     will not be available on FIPS-compliant systems.
       #
       #
-      # **This method is kept for compatibility.** This should only be used when the
-      # SEC 1/RFC 5915 ECPrivateKey format is required.
+      # <strong>This method is kept for compatibility.</strong> This should only be
+      # used when the SEC 1/RFC 5915 ECPrivateKey format is required.
       #
       # Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
       # (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
@@ -6491,8 +6566,8 @@ module OpenSSL
       #
       # See #to_pem for details.
       #
-      # **This method is kept for compatibility.** This should only be used when the
-      # SEC 1/RFC 5915 ECPrivateKey format is required.
+      # <strong>This method is kept for compatibility.</strong> This should only be
+      # used when the SEC 1/RFC 5915 ECPrivateKey format is required.
       #
       # Consider using #public_to_der or #private_to_der instead.
       #
@@ -6544,8 +6619,8 @@ module OpenSSL
       #     will not be available on FIPS-compliant systems.
       #
       #
-      # **This method is kept for compatibility.** This should only be used when the
-      # SEC 1/RFC 5915 ECPrivateKey format is required.
+      # <strong>This method is kept for compatibility.</strong> This should only be
+      # used when the SEC 1/RFC 5915 ECPrivateKey format is required.
       #
       # Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
       # (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
@@ -6638,9 +6713,10 @@ module OpenSSL
 
         # <!--
         #   rdoc-file=ext/openssl/ossl_pkey_ec.c
-        #   - group.curve_name  => String
+        #   - group.curve_name -> string or nil
         # -->
-        # Returns the curve name (sn).
+        # Returns the curve name (short name) corresponding to this group, or `nil` if
+        # OpenSSL does not have an OID associated with the group.
         #
         # See the OpenSSL documentation for EC_GROUP_get_curve_name()
         #
@@ -6702,14 +6778,14 @@ module OpenSSL
         #
         # *format* can be one of these:
         #
-        # `:compressed`
+        # <code>:compressed</code>
         # :   Encoded as z||x, where z is an octet indicating which solution of the
         #     equation y is. z will be 0x02 or 0x03.
         #
-        # `:uncompressed`
+        # <code>:uncompressed</code>
         # :   Encoded as z||x||y, where z is an octet 0x04.
         #
-        # `:hybrid`
+        # <code>:hybrid</code>
         # :   Encodes as z||x||y, where z is an octet indicating which solution of the
         #     equation y is. z will be 0x06 or 0x07.
         #
@@ -6850,18 +6926,16 @@ module OpenSSL
         # <!--
         #   rdoc-file=ext/openssl/ossl_pkey_ec.c
         #   - point.mul(bn1 [, bn2]) => point
-        #   - point.mul(bns, points [, bn2]) => point
         # -->
         # Performs elliptic curve point multiplication.
         #
-        # The first form calculates `bn1 * point + bn2 * G`, where `G` is the generator
-        # of the group of *point*. *bn2* may be omitted, and in that case, the result is
-        # just `bn1 * point`.
+        # The first form calculates <code>bn1 * point + bn2 * G</code>, where `G` is the
+        # generator of the group of *point*. *bn2* may be omitted, and in that case, the
+        # result is just <code>bn1 * point</code>.
         #
-        # The second form calculates `bns[0] * point + bns[1] * points[0] + ... +
-        # bns[-1] * points[-1] + bn2 * G`. *bn2* may be omitted. *bns* must be an array
-        # of OpenSSL::BN. *points* must be an array of OpenSSL::PKey::EC::Point. Please
-        # note that `points[0]` is not multiplied by `bns[0]`, but `bns[1]`.
+        # Before version 4.0.0, and when compiled with OpenSSL 1.1.1 or older, this
+        # method allowed another form:
+        #     point.mul(bns, points [, bn2]) => point
         #
         def mul: (bn bn1, ?bn bn2) -> self
                | (Array[bn] bns, Array[self], ?bn bn2) -> self
@@ -6902,9 +6976,9 @@ module OpenSSL
         #
         # *conversion_form* specifies how the point is converted. Possible values are:
         #
-        # *   `:compressed`
-        # *   `:uncompressed`
-        # *   `:hybrid`
+        # *   <code>:compressed</code>
+        # *   <code>:uncompressed</code>
+        # *   <code>:hybrid</code>
         #
         def to_octet_string: (point_conversion_format) -> String
 
@@ -7103,6 +7177,15 @@ module OpenSSL
     # <!-- rdoc-file=ext/openssl/ossl_pkey.c -->
     # Raised when errors occur during PKey#sign or PKey#verify.
     #
+    # Before version 4.0.0, OpenSSL::PKey::PKeyError had the following subclasses.
+    # These subclasses have been removed and the constants are now defined as
+    # aliases of OpenSSL::PKey::PKeyError.
+    #
+    # *   OpenSSL::PKey::DHError
+    # *   OpenSSL::PKey::DSAError
+    # *   OpenSSL::PKey::ECError
+    # *   OpenSSL::PKey::RSAError
+    #
     class PKeyError < OpenSSL::OpenSSLError
     end
 
@@ -7194,8 +7277,8 @@ module OpenSSL
       #     will not be available on FIPS-compliant systems.
       #
       #
-      # **This method is kept for compatibility.** This should only be used when the
-      # PKCS #1 RSAPrivateKey format is required.
+      # <strong>This method is kept for compatibility.</strong> This should only be
+      # used when the PKCS #1 RSAPrivateKey format is required.
       #
       # Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
       # (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
@@ -7210,15 +7293,12 @@ module OpenSSL
       def p: () -> BN?
 
       # <!--
-      #   rdoc-file=ext/openssl/ossl_pkey_rsa.c
-      #   - rsa.params => hash
+      #   rdoc-file=ext/openssl/lib/openssl/pkey.rb
+      #   - rsa.params -> hash
       # -->
-      # THIS METHOD IS INSECURE, PRIVATE INFORMATION CAN LEAK OUT!!!
-      #
-      # Stores all parameters of key to the hash.  The hash has keys 'n', 'e', 'd',
-      # 'p', 'q', 'dmp1', 'dmq1', 'iqmp'.
+      # Stores all parameters of key to a Hash.
       #
-      # Don't use :-)) (It's up to you)
+      # The hash has keys 'n', 'e', 'd', 'p', 'q', 'dmp1', 'dmq1', and 'iqmp'.
       #
       def params: () -> Hash[String, BN?]
 
@@ -7239,8 +7319,8 @@ module OpenSSL
       # private key. `padding` defaults to PKCS1_PADDING, which is known to be
       # insecure but is kept for backwards compatibility.
       #
-      # **Deprecated in version 3.0**. Consider using PKey::PKey#encrypt and
-      # PKey::PKey#decrypt instead.
+      # <strong>Deprecated in version 3.0</strong>. Consider using PKey::PKey#encrypt
+      # and PKey::PKey#decrypt instead.
       #
       def private_decrypt: (String data, ?Integer padding) -> String
 
@@ -7253,8 +7333,8 @@ module OpenSSL
       # which is known to be insecure but is kept for backwards compatibility. The
       # encrypted string output can be decrypted using #public_decrypt.
       #
-      # **Deprecated in version 3.0**. Consider using PKey::PKey#sign_raw and
-      # PKey::PKey#verify_raw, and PKey::PKey#verify_recover instead.
+      # <strong>Deprecated in version 3.0</strong>. Consider using PKey::PKey#sign_raw
+      # and PKey::PKey#verify_raw, and PKey::PKey#verify_recover instead.
       #
       def private_encrypt: (String data, ?Integer padding) -> String
 
@@ -7276,8 +7356,8 @@ module OpenSSL
       # public key.  `padding` defaults to PKCS1_PADDING which is known to be insecure
       # but is kept for backwards compatibility.
       #
-      # **Deprecated in version 3.0**. Consider using PKey::PKey#sign_raw and
-      # PKey::PKey#verify_raw, and PKey::PKey#verify_recover instead.
+      # <strong>Deprecated in version 3.0</strong>. Consider using PKey::PKey#sign_raw
+      # and PKey::PKey#verify_raw, and PKey::PKey#verify_recover instead.
       #
       def public_decrypt: (String data, ?Integer padding) -> String
 
@@ -7290,8 +7370,8 @@ module OpenSSL
       # which is known to be insecure but is kept for backwards compatibility. The
       # encrypted string output can be decrypted using #private_decrypt.
       #
-      # **Deprecated in version 3.0**. Consider using PKey::PKey#encrypt and
-      # PKey::PKey#decrypt instead.
+      # <strong>Deprecated in version 3.0</strong>. Consider using PKey::PKey#encrypt
+      # and PKey::PKey#decrypt instead.
       #
       def public_encrypt: (String data, ?Integer padding) -> String
 
@@ -7315,8 +7395,9 @@ module OpenSSL
       #   rdoc-file=ext/openssl/ossl_pkey_rsa.c
       #   - rsa.set_crt_params(dmp1, dmq1, iqmp) -> self
       # -->
-      # Sets *dmp1*, *dmq1*, *iqmp* for the RSA instance. They are calculated by `d
-      # mod (p - 1)`, `d mod (q - 1)` and `q^(-1) mod p` respectively.
+      # Sets *dmp1*, *dmq1*, *iqmp* for the RSA instance. They are calculated by
+      # <code>d mod (p - 1)</code>, <code>d mod (q - 1)</code> and <code>q^(-1) mod
+      # p</code> respectively.
       #
       def set_crt_params: (bn dmp1, bn dmq1, bn iqmp) -> self
 
@@ -7343,7 +7424,7 @@ module OpenSSL
       # Signs *data* using the Probabilistic Signature Scheme (RSA-PSS) and returns
       # the calculated signature.
       #
-      # RSAError will be raised if an error occurs.
+      # PKeyError will be raised if an error occurs.
       #
       # See #verify_pss for the verification operation.
       #
@@ -7356,9 +7437,9 @@ module OpenSSL
       #
       # *salt_length*
       # :   The length in octets of the salt. Two special values are reserved:
-      #     `:digest` means the digest length, and `:max` means the maximum possible
-      #     length for the combination of the private key and the selected message
-      #     digest algorithm.
+      #     <code>:digest</code> means the digest length, and <code>:max</code> means
+      #     the maximum possible length for the combination of the private key and the
+      #     selected message digest algorithm.
       #
       # *mgf1_hash*
       # :   The hash algorithm used in MGF1 (the currently supported mask generation
@@ -7383,8 +7464,8 @@ module OpenSSL
       #
       # See #to_pem for details.
       #
-      # **This method is kept for compatibility.** This should only be used when the
-      # PKCS #1 RSAPrivateKey format is required.
+      # <strong>This method is kept for compatibility.</strong> This should only be
+      # used when the PKCS #1 RSAPrivateKey format is required.
       #
       # Consider using #public_to_der or #private_to_der instead.
       #
@@ -7436,8 +7517,8 @@ module OpenSSL
       #     will not be available on FIPS-compliant systems.
       #
       #
-      # **This method is kept for compatibility.** This should only be used when the
-      # PKCS #1 RSAPrivateKey format is required.
+      # <strong>This method is kept for compatibility.</strong> This should only be
+      # used when the PKCS #1 RSAPrivateKey format is required.
       #
       # Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
       # (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
@@ -7490,8 +7571,8 @@ module OpenSSL
       #     will not be available on FIPS-compliant systems.
       #
       #
-      # **This method is kept for compatibility.** This should only be used when the
-      # PKCS #1 RSAPrivateKey format is required.
+      # <strong>This method is kept for compatibility.</strong> This should only be
+      # used when the PKCS #1 RSAPrivateKey format is required.
       #
       # Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
       # (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
@@ -7517,7 +7598,7 @@ module OpenSSL
       # Verifies *data* using the Probabilistic Signature Scheme (RSA-PSS).
       #
       # The return value is `true` if the signature is valid, `false` otherwise.
-      # RSAError will be raised if an error occurs.
+      # PKeyError will be raised if an error occurs.
       #
       # See #sign_pss for the signing operation and an example code.
       #
@@ -7530,8 +7611,8 @@ module OpenSSL
       #
       # *salt_length*
       # :   The length in octets of the salt. Two special values are reserved:
-      #     `:digest` means the digest length, and `:auto` means automatically
-      #     determining the length based on the signature.
+      #     <code>:digest</code> means the digest length, and <code>:auto</code> means
+      #     automatically determining the length based on the signature.
       #
       # *mgf1_hash*
       # :   The hash algorithm used in MGF1.
@@ -7551,7 +7632,7 @@ module OpenSSL
       #
       # If called without arguments, creates a new instance with no key components
       # set. They can be set individually by #set_key, #set_factors, and
-      # #set_crt_params.
+      # #set_crt_params. This form is not compatible with OpenSSL 3.0 or later.
       #
       # If called with a String, tries to parse as DER or PEM encoding of an RSA key.
       # Note that if *password* is not specified, but the key is encrypted with a
@@ -7586,10 +7667,17 @@ module OpenSSL
       SSLV23_PADDING: Integer
     end
 
-    # <!-- rdoc-file=ext/openssl/ossl_pkey_rsa.c -->
-    # Generic exception that is raised if an operation on an RSA PKey fails
-    # unexpectedly or in case an instantiation of an instance of RSA fails due to
-    # non-conformant input data.
+    # <!-- rdoc-file=ext/openssl/ossl_pkey.c -->
+    # Raised when errors occur during PKey#sign or PKey#verify.
+    #
+    # Before version 4.0.0, OpenSSL::PKey::PKeyError had the following subclasses.
+    # These subclasses have been removed and the constants are now defined as
+    # aliases of OpenSSL::PKey::PKeyError.
+    #
+    # *   OpenSSL::PKey::DHError
+    # *   OpenSSL::PKey::DSAError
+    # *   OpenSSL::PKey::ECError
+    # *   OpenSSL::PKey::RSAError
     #
     class RSAError < OpenSSL::PKey::PKeyError
     end
@@ -8029,9 +8117,14 @@ module OpenSSL
       #   - ctx.ciphers = [name, ...]
       #   - ctx.ciphers = [[name, version, bits, alg_bits], ...]
       # -->
-      # Sets the list of available cipher suites for this context.  Note in a server
-      # context some ciphers require the appropriate certificates.  For example, an
-      # RSA cipher suite can only be chosen when an RSA certificate is available.
+      # Sets the list of available cipher suites for TLS 1.2 and below for this
+      # context.
+      #
+      # Note in a server context some ciphers require the appropriate certificates.
+      # For example, an RSA cipher suite can only be chosen when an RSA certificate is
+      # available.
+      #
+      # This method does not affect TLS 1.3 connections. See also #ciphersuites=.
       #
       def ciphers=: (Array[[ String, String, Integer, Integer ]] ciphers) -> void
                   | (Array[String] ciphers) -> void
@@ -8067,24 +8160,25 @@ module OpenSSL
       #
       def client_cert_cb=: (^(Session) -> [ X509::Certificate, PKey::PKey ]? client_cert_cb) -> void
 
-      # <!--
-      #   rdoc-file=ext/openssl/ossl_ssl.c
-      #   - ctx.ecdh_curves = curve_list -> curve_list
-      # -->
-      # Sets the list of "supported elliptic curves" for this context.
+      # <!-- rdoc-file=ext/openssl/ossl_ssl.c -->
+      # Sets the list of supported groups for key agreement for this context.
+      #
+      # For a TLS client, the list is directly used in the "supported_groups"
+      # extension. For a server, the list is used by OpenSSL to determine the set of
+      # shared supported groups. OpenSSL will pick the most appropriate one from it.
+      #
+      # #ecdh_curves= is a deprecated alias for #groups=.
       #
-      # For a TLS client, the list is directly used in the Supported Elliptic Curves
-      # Extension. For a server, the list is used by OpenSSL to determine the set of
-      # shared curves. OpenSSL will pick the most appropriate one from it.
+      # See also the man page SSL_CTX_set1_groups_list(3).
       #
       # ### Example
       #     ctx1 = OpenSSL::SSL::SSLContext.new
-      #     ctx1.ecdh_curves = "X25519:P-256:P-224"
+      #     ctx1.groups = "X25519:P-256:P-224"
       #     svr = OpenSSL::SSL::SSLServer.new(tcp_svr, ctx1)
       #     Thread.new { svr.accept }
       #
       #     ctx2 = OpenSSL::SSL::SSLContext.new
-      #     ctx2.ecdh_curves = "P-256"
+      #     ctx2.groups = "P-256"
       #     cli = OpenSSL::SSL::SSLSocket.new(tcp_sock, ctx2)
       #     cli.connect
       #
@@ -8149,7 +8243,7 @@ module OpenSSL
       def key=: (PKey::PKey) -> PKey::PKey
 
       # <!--
-      #   rdoc-file=ext/openssl/lib/openssl/ssl.rb
+      #   rdoc-file=ext/openssl/ossl_ssl.c
       #   - ctx.max_version = OpenSSL::SSL::TLS1_2_VERSION
       #   - ctx.max_version = :TLS1_2
       #   - ctx.max_version = nil
@@ -8160,7 +8254,7 @@ module OpenSSL
       def max_version=: (tls_version version) -> tls_version
 
       # <!--
-      #   rdoc-file=ext/openssl/lib/openssl/ssl.rb
+      #   rdoc-file=ext/openssl/ossl_ssl.c
       #   - ctx.min_version = OpenSSL::SSL::TLS1_2_VERSION
       #   - ctx.min_version = :TLS1_2
       #   - ctx.min_version = nil
@@ -8169,9 +8263,6 @@ module OpenSSL
       # may be specified by an integer constant named OpenSSL::SSL::*_VERSION, a
       # Symbol, or `nil` which means "any version".
       #
-      # Be careful that you don't overwrite OpenSSL::SSL::OP_NO_{SSL,TLS}v* options by
-      # #options= once you have called #min_version= or #max_version=.
-      #
       # ### Example
       #     ctx = OpenSSL::SSL::SSLContext.new
       #     ctx.min_version = OpenSSL::SSL::TLS1_1_VERSION
@@ -8255,8 +8346,8 @@ module OpenSSL
       #   - ctx.options = integer
       # -->
       # Sets various OpenSSL options. The options are a bit field and can be combined
-      # with the bitwise OR operator (`|`). Available options are defined as constants
-      # in OpenSSL::SSL that begin with `OP_`.
+      # with the bitwise OR operator (<code>|</code>). Available options are defined
+      # as constants in OpenSSL::SSL that begin with `OP_`.
       #
       # For backwards compatibility, passing `nil` has the same effect as passing
       # OpenSSL::SSL::OP_ALL.
@@ -8581,7 +8672,7 @@ module OpenSSL
       #
       def timeout=: (Integer) -> Integer
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/ssl.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_ssl.c -->
       # A callback invoked when DH parameters are required for ephemeral DH key
       # exchange.
       #
@@ -8591,11 +8682,11 @@ module OpenSSL
       # The callback must return an OpenSSL::PKey::DH instance of the correct key
       # length.
       #
-      # **Deprecated in version 3.0.** Use #tmp_dh= instead.
+      # <strong>Deprecated in version 3.0.</strong> Use #tmp_dh= instead.
       #
       def tmp_dh_callback: () -> (^(Session, Integer, Integer) -> PKey::DH | nil)
 
-      # <!-- rdoc-file=ext/openssl/lib/openssl/ssl.rb -->
+      # <!-- rdoc-file=ext/openssl/ossl_ssl.c -->
       # A callback invoked when DH parameters are required for ephemeral DH key
       # exchange.
       #
@@ -8605,7 +8696,7 @@ module OpenSSL
       # The callback must return an OpenSSL::PKey::DH instance of the correct key
       # length.
       #
-      # **Deprecated in version 3.0.** Use #tmp_dh= instead.
+      # <strong>Deprecated in version 3.0.</strong> Use #tmp_dh= instead.
       #
       def tmp_dh_callback=: (^(Session, Integer, Integer) -> PKey::DH) -> void
 
@@ -8866,8 +8957,8 @@ module OpenSSL
       #   rdoc-file=ext/openssl/lib/openssl/ssl.rb
       #   - open(remote_host, remote_port, local_host=nil, local_port=nil, context: nil)
       # -->
-      # Creates a new instance of SSLSocket. *remote*host_ and *remote*port_ are used
-      # to open TCPSocket. If *local*host_ and *local*port_ are specified, then those
+      # Creates a new instance of SSLSocket. _remote_host_ and _remote_port_ are used
+      # to open TCPSocket. If _local_host_ and _local_port_ are specified, then those
       # parameters are used on the local end to establish the connection. If *context*
       # is provided, the SSL Sockets initial params will be taken from the context.
       #
@@ -8911,7 +9002,8 @@ module OpenSSL
       #
       # By specifying a keyword argument *exception* to `false`, you can indicate that
       # accept_nonblock should not raise an IO::WaitReadable or IO::WaitWritable
-      # exception, but return the symbol `:wait_readable` or `:wait_writable` instead.
+      # exception, but return the symbol <code>:wait_readable</code> or
+      # <code>:wait_writable</code> instead.
       #
       def accept_nonblock: (?exception: true) -> self
                          | (exception: false) -> (self | :wait_readable | :wait_writable)
@@ -8944,7 +9036,7 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_ssl.c
-      #   - ssl.client_ca => [x509name, ...]
+      #   - ssl.client_ca => [x509name, ...] or nil
       # -->
       # Returns the list of client CAs. Please note that in contrast to
       # SSLContext#client_ca= no array of X509::Certificate is returned but X509::Name
@@ -8982,7 +9074,8 @@ module OpenSSL
       #
       # By specifying a keyword argument *exception* to `false`, you can indicate that
       # connect_nonblock should not raise an IO::WaitReadable or IO::WaitWritable
-      # exception, but return the symbol `:wait_readable` or `:wait_writable` instead.
+      # exception, but return the symbol <code>:wait_readable</code> or
+      # <code>:wait_writable</code> instead.
       #
       def connect_nonblock: (?exception: true) -> self
                           | (exception: false) -> (self | :wait_readable | :wait_writable)
@@ -9498,9 +9591,10 @@ module OpenSSL
     # Assume we received a timestamp request that has set Request#policy_id to `nil`
     # and Request#cert_requested? to true. The raw request bytes are stored in a
     # variable called `req_raw`. We'd still like to integrate the necessary
-    # intermediate certificates (in `inter1.cer` and `inter2.cer`) to simplify
-    # validation of the resulting Response. `ts.p12` is a PKCS#12-compatible file
-    # including the private key and the timestamping certificate.
+    # intermediate certificates (in <code>inter1.cer</code> and
+    # <code>inter2.cer</code>) to simplify validation of the resulting Response.
+    # <code>ts.p12</code> is a PKCS#12-compatible file including the private key and
+    # the timestamping certificate.
     #
     #     req = OpenSSL::Timestamp::Request.new(raw_bytes)
     #     p12 = OpenSSL::PKCS12.new(File.binread('ts.p12'), 'pwd')
@@ -9515,65 +9609,33 @@ module OpenSSL
     #     fac.additional_certificates = [ inter1, inter2 ]
     #     timestamp = fac.create_timestamp(p12.key, p12.certificate, req)
     #
-    # ## Attributes
-    #
-    # ### default_policy_id
-    #
-    # Request#policy_id will always be preferred over this if present in the
-    # Request, only if Request#policy_id is nil default_policy will be used. If none
-    # of both is present, a TimestampError will be raised when trying to create a
-    # Response.
-    #
-    # call-seq:
-    #     factory.default_policy_id = "string" -> string
-    #     factory.default_policy_id            -> string or nil
-    #
-    # ### serial_number
-    #
-    # Sets or retrieves the serial number to be used for timestamp creation. Must be
-    # present for timestamp creation.
-    #
-    # call-seq:
-    #     factory.serial_number = number -> number
-    #     factory.serial_number          -> number or nil
-    #
-    # ### gen_time
-    #
-    # Sets or retrieves the Time value to be used in the Response. Must be present
-    # for timestamp creation.
-    #
-    # call-seq:
-    #     factory.gen_time = Time -> Time
-    #     factory.gen_time        -> Time or nil
-    #
-    # ### additional_certs
-    #
-    # Sets or retrieves additional certificates apart from the timestamp certificate
-    # (e.g. intermediate certificates) to be added to the Response. Must be an Array
-    # of OpenSSL::X509::Certificate.
-    #
-    # call-seq:
-    #     factory.additional_certs = [cert1, cert2] -> [ cert1, cert2 ]
-    #     factory.additional_certs                  -> array or nil
-    #
-    # ### allowed_digests
-    #
-    # Sets or retrieves the digest algorithms that the factory is allowed create
-    # timestamps for. Known vulnerable or weak algorithms should not be allowed
-    # where possible. Must be an Array of String or OpenSSL::Digest subclass
-    # instances.
-    #
-    # call-seq:
-    #     factory.allowed_digests = ["sha1", OpenSSL::Digest.new('SHA256').new] -> [ "sha1", OpenSSL::Digest) ]
-    #     factory.allowed_digests                                               -> array or nil
-    #
     class Factory
+      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
+      # Additional certificates apart from the timestamp certificate (e.g.
+      # intermediate certificates) to be added to the Response. Must be an Array of
+      # OpenSSL::X509::Certificate, or `nil`.
+      #
       def additional_certs: () -> Array[X509::Certificate]?
 
+      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
+      # Additional certificates apart from the timestamp certificate (e.g.
+      # intermediate certificates) to be added to the Response. Must be an Array of
+      # OpenSSL::X509::Certificate, or `nil`.
+      #
       def additional_certs=: (Array[X509::Certificate]? certs) -> Array[X509::Certificate]?
 
+      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
+      # The list of digest algorithms that the factory is allowed create timestamps
+      # for. Known vulnerable or weak algorithms should not be allowed where possible.
+      # Must be an Array of String or OpenSSL::Digest subclass instances.
+      #
       def allowed_digests: () -> Array[String | Digest]?
 
+      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
+      # The list of digest algorithms that the factory is allowed create timestamps
+      # for. Known vulnerable or weak algorithms should not be allowed where possible.
+      # Must be an Array of String or OpenSSL::Digest subclass instances.
+      #
       def allowed_digests=: (Array[String | Digest]) -> Array[String | Digest]
 
       # <!--
@@ -9602,16 +9664,48 @@ module OpenSSL
       #
       def create_timestamp: (PKey::PKey key, X509::Certificate cert, Request request) -> Response
 
+      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
+      # A String representing the default policy object identifier, or `nil`.
+      #
+      # Request#policy_id will always be preferred over this if present in the
+      # Request, only if Request#policy_id is `nil` default_policy will be used. If
+      # none of both is present, a TimestampError will be raised when trying to create
+      # a Response.
+      #
       def default_policy_id: () -> String?
 
+      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
+      # A String representing the default policy object identifier, or `nil`.
+      #
+      # Request#policy_id will always be preferred over this if present in the
+      # Request, only if Request#policy_id is `nil` default_policy will be used. If
+      # none of both is present, a TimestampError will be raised when trying to create
+      # a Response.
+      #
       def default_policy_id=: (String) -> String
 
+      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
+      # The Time value to be used in the Response. Must be present for timestamp
+      # creation.
+      #
       def gen_time: () -> Time?
 
+      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
+      # The Time value to be used in the Response. Must be present for timestamp
+      # creation.
+      #
       def gen_time=: (Time) -> Time
 
+      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
+      # The serial number to be used for timestamp creation. Must be present for
+      # timestamp creation. Must be an instance of OpenSSL::BN or Integer.
+      #
       def serial_number: () -> Integer?
 
+      # <!-- rdoc-file=ext/openssl/ossl_ts.c -->
+      # The serial number to be used for timestamp creation. Must be present for
+      # timestamp creation. Must be an instance of OpenSSL::BN or Integer.
+      #
       def serial_number=: (Integer) -> Integer
     end
 
@@ -10305,8 +10399,10 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509attr.c
-      #   - attr.oid => string
+      #   - attr.oid -> string
       # -->
+      # Returns the OID of the attribute. Returns the short name or the dotted decimal
+      # notation.
       #
       def oid: () -> String
 
@@ -10468,8 +10564,12 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509crl.c
-      #   - signature_algorithm()
+      #   - crl.signature_algorithm -> string
       # -->
+      # Returns the signature algorithm used to sign this CRL.
+      #
+      # Returns the long name of the signature algorithm, or the dotted decimal
+      # notation if OpenSSL does not define a long name for it.
       #
       def signature_algorithm: () -> String
 
@@ -10649,6 +10749,12 @@ module OpenSSL
       # Compares the two certificates. Note that this takes into account all fields,
       # not just the issuer name and the serial number.
       #
+      # This method uses X509_cmp() from OpenSSL, which compares certificates based on
+      # their cached DER encodings. The comparison can be unreliable if a certificate
+      # is incomplete.
+      #
+      # See also the man page X509_cmp(3).
+      #
       def ==: (self other) -> bool
 
       # <!--
@@ -10682,7 +10788,7 @@ module OpenSSL
       def extensions=: (Array[Extension]) -> Array[Extension]
 
       # <!--
-      #   rdoc-file=ext/openssl/ossl_x509cert.c
+      #   rdoc-file=ext/openssl/lib/openssl/x509.rb
       #   - inspect()
       # -->
       #
@@ -10776,6 +10882,12 @@ module OpenSSL
       #   rdoc-file=ext/openssl/ossl_x509cert.c
       #   - cert.signature_algorithm => string
       # -->
+      # Returns the signature algorithm used to sign this certificate. This returns
+      # the algorithm name found in the TBSCertificate structure, not the outer
+      # Certificate structure.
+      #
+      # Returns the long name of the signature algorithm, or the dotted decimal
+      # notation if OpenSSL does not define a long name for it.
       #
       def signature_algorithm: () -> String
 
@@ -10893,8 +11005,10 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509ext.c
-      #   - oid()
+      #   - ext.oid -> string
       # -->
+      # Returns the OID of the extension. Returns the short name or the dotted decimal
+      # notation.
       #
       def oid: () -> String
 
@@ -11196,11 +11310,11 @@ module OpenSSL
       # Parses the string representation of a distinguished name. Two different forms
       # are supported:
       #
-      # *   OpenSSL format (`X509_NAME_oneline()`) used by `#to_s`. For example:
-      #     `/DC=com/DC=example/CN=nobody`
-      # *   OpenSSL format (`X509_NAME_print()`) used by
-      #     `#to_s(OpenSSL::X509::Name::COMPAT)`. For example: `DC=com, DC=example,
-      #     CN=nobody`
+      # *   OpenSSL format (<code>X509_NAME_oneline()</code>) used by
+      #     <code>#to_s</code>. For example: <code>/DC=com/DC=example/CN=nobody</code>
+      # *   OpenSSL format (<code>X509_NAME_print()</code>) used by
+      #     <code>#to_s(OpenSSL::X509::Name::COMPAT)</code>. For example:
+      #     <code>DC=com, DC=example, CN=nobody</code>
       #
       # Neither of them is standardized and has quirks and inconsistencies in handling
       # of escaped characters or multi-valued RDNs.
@@ -11222,9 +11336,9 @@ module OpenSSL
       def self.parse_rfc2253: (String str, ?template template) -> instance
 
       # <!-- rdoc-file=ext/openssl/ossl_x509name.c -->
-      # Compares this Name with *other* and returns `0` if they are the same and `-1`
-      # or `+1` if they are greater or less than each other respectively. Returns
-      # `nil` if they are not comparable (i.e. different types).
+      # Compares this Name with *other* and returns `0` if they are the same and
+      # <code>-1</code> or ++1+ if they are greater or less than each other
+      # respectively. Returns `nil` if they are not comparable (i.e. different types).
       #
       alias <=> cmp
 
@@ -11266,9 +11380,9 @@ module OpenSSL
       #   - name.cmp(other) -> -1 | 0 | 1 | nil
       #   - name <=> other  -> -1 | 0 | 1 | nil
       # -->
-      # Compares this Name with *other* and returns `0` if they are the same and `-1`
-      # or `+1` if they are greater or less than each other respectively. Returns
-      # `nil` if they are not comparable (i.e. different types).
+      # Compares this Name with *other* and returns `0` if they are the same and
+      # <code>-1</code> or ++1+ if they are greater or less than each other
+      # respectively. Returns `nil` if they are not comparable (i.e. different types).
       #
       def cmp: (untyped other) -> Integer?
 
@@ -11336,14 +11450,14 @@ module OpenSSL
       # *   OpenSSL::X509::Name::MULTILINE
       #
       # If *format* is omitted, the largely broken and traditional OpenSSL format
-      # (`X509_NAME_oneline()` format) is chosen.
+      # (<code>X509_NAME_oneline()</code> format) is chosen.
       #
-      # **Use of this method is discouraged.** None of the formats other than
-      # OpenSSL::X509::Name::RFC2253 is standardized and may show an inconsistent
+      # <strong>Use of this method is discouraged.</strong> None of the formats other
+      # than OpenSSL::X509::Name::RFC2253 is standardized and may show an inconsistent
       # behavior through OpenSSL versions.
       #
       # It is recommended to use #to_utf8 instead, which is equivalent to calling
-      # `name.to_s(OpenSSL::X509::Name::RFC2253).force_encoding("UTF-8")`.
+      # <code>name.to_s(OpenSSL::X509::Name::RFC2253).force_encoding("UTF-8")</code>.
       #
       def to_s: (?format format) -> String
 
@@ -11547,8 +11661,12 @@ module OpenSSL
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_x509req.c
-      #   - signature_algorithm()
+      #   - req.signature_algorithm -> string
       # -->
+      # Returns the signature algorithm used to sign this request.
+      #
+      # Returns the long name of the signature algorithm, or the dotted decimal
+      # notation if OpenSSL does not define a long name for it.
       #
       def signature_algorithm: () -> String