diff --git a/crypto/poly1305/poly1305_test.txt b/crypto/poly1305/poly1305_test.txt
index 2a92c12..ad40699 100644
--- a/crypto/poly1305/poly1305_test.txt
+++ b/crypto/poly1305/poly1305_test.txt
@@ -1,4 +1,4 @@
-# RFC 7359, section 2.5.2.
+# RFC 7539, section 2.5.2.
 
 Key = 85d6be7857556d337f4452fe42d506a80103808afb0db2fd4abff6af4149f51b
 Input = "Cryptographic Forum Research Group"
diff --git a/include/openssl/aead.h b/include/openssl/aead.h
index 16676c5..4f822e8 100644
--- a/include/openssl/aead.h
+++ b/include/openssl/aead.h
@@ -134,7 +134,7 @@
  * block counter, thus the maximum plaintext size is 64GB. */
 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ctr_hmac_sha256(void);
 
-/* EVP_aead_aes_128_ctr_hmac_sha256 is AES-256 in CTR mode with HMAC-SHA256 for
+/* EVP_aead_aes_256_ctr_hmac_sha256 is AES-256 in CTR mode with HMAC-SHA256 for
  * authentication. See |EVP_aead_aes_128_ctr_hmac_sha256| for details. */
 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_ctr_hmac_sha256(void);
 
diff --git a/include/openssl/bio.h b/include/openssl/bio.h
index 44de50f..8d47594 100644
--- a/include/openssl/bio.h
+++ b/include/openssl/bio.h
@@ -728,10 +728,11 @@
 
 /* Deprecated functions. */
 
-/* Returns a filter |BIO| that base64-encodes data written into it, and decodes
- * data read from it. |BIO_gets| is not supported. Call |BIO_flush| when done
- * writing, to signal that no more data are to be encoded. The flag
- * |BIO_FLAGS_BASE64_NO_NL| may be set to encode all the data on one line. */
+/* BIO_f_base64 returns a filter |BIO| that base64-encodes data written into
+ * it, and decodes data read from it. |BIO_gets| is not supported. Call
+ * |BIO_flush| when done writing, to signal that no more data are to be
+ * encoded. The flag |BIO_FLAGS_BASE64_NO_NL| may be set to encode all the data
+ * on one line. */
 OPENSSL_EXPORT const BIO_METHOD *BIO_f_base64(void);
 
 /* ERR_print_errors is an alias for |BIO_print_errors|. */
diff --git a/include/openssl/bn.h b/include/openssl/bn.h
index c9bdb1e..1a3958f 100644
--- a/include/openssl/bn.h
+++ b/include/openssl/bn.h
@@ -532,7 +532,7 @@
 OPENSSL_EXPORT int BN_mod_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b,
                               const BIGNUM *m, BN_CTX *ctx);
 
-/* BN_mod_mul sets |r| = |a|^2 mod |m|. It returns one on success and zero
+/* BN_mod_sqr sets |r| = |a|^2 mod |m|. It returns one on success and zero
  * on error. */
 OPENSSL_EXPORT int BN_mod_sqr(BIGNUM *r, const BIGNUM *a, const BIGNUM *m,
                               BN_CTX *ctx);
@@ -813,7 +813,7 @@
  * find the needed amount of space, call the function with |out| set to NULL. */
 OPENSSL_EXPORT size_t BN_bn2mpi(const BIGNUM *in, uint8_t *out);
 
-/* BN_bin2bn parses |len| bytes from |in| and returns the resulting value. The
+/* BN_mpi2bn parses |len| bytes from |in| and returns the resulting value. The
  * bytes at |in| are expected to be in the format emitted by |BN_bn2mpi|.
  *
  * If |out| is NULL then a fresh |BIGNUM| is allocated and returned, otherwise
diff --git a/include/openssl/cipher.h b/include/openssl/cipher.h
index a4e79dd..fb7171f 100644
--- a/include/openssl/cipher.h
+++ b/include/openssl/cipher.h
@@ -91,17 +91,6 @@
 OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_ofb(void);
 OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_xts(void);
 
-/* Deprecated AES-GCM implementations that set |EVP_CIPH_FLAG_CUSTOM_CIPHER|.
- * Use |EVP_aead_aes_128_gcm| and |EVP_aead_aes_256_gcm| instead. */
-OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_gcm(void);
-OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_gcm(void);
-
-/* Deprecated 192-bit version of AES. */
-OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_ecb(void);
-OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_cbc(void);
-OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_ctr(void);
-OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_gcm(void);
-
 /* EVP_enc_null returns a 'cipher' that passes plaintext through as
  * ciphertext. */
 OPENSSL_EXPORT const EVP_CIPHER *EVP_enc_null(void);
@@ -407,6 +396,18 @@
  * |name|, or NULL if the name is unknown. */
 OPENSSL_EXPORT const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
 
+/* These AEADs are deprecated AES-GCM implementations that set
+ * |EVP_CIPH_FLAG_CUSTOM_CIPHER|. Use |EVP_aead_aes_128_gcm| and
+ * |EVP_aead_aes_256_gcm| instead. */
+OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_128_gcm(void);
+OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_gcm(void);
+
+/* These are deprecated, 192-bit version of AES. */
+OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_ecb(void);
+OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_cbc(void);
+OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_ctr(void);
+OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_192_gcm(void);
+
 
 /* Private functions. */
 
diff --git a/include/openssl/ecdsa.h b/include/openssl/ecdsa.h
index b7f15c4..f3f68eb 100644
--- a/include/openssl/ecdsa.h
+++ b/include/openssl/ecdsa.h
@@ -106,14 +106,14 @@
 /* ECDSA_SIG_free frees |sig| its member |BIGNUM|s. */
 OPENSSL_EXPORT void ECDSA_SIG_free(ECDSA_SIG *sig);
 
-/* ECDSA_sign signs |digest_len| bytes from |digest| with |key| and returns the
- * resulting signature structure, or NULL on error. */
+/* ECDSA_do_sign signs |digest_len| bytes from |digest| with |key| and returns
+ * the resulting signature structure, or NULL on error. */
 OPENSSL_EXPORT ECDSA_SIG *ECDSA_do_sign(const uint8_t *digest,
                                         size_t digest_len, EC_KEY *key);
 
-/* ECDSA_verify verifies that |sig| constitutes a valid signature by |key| of
- * |digest|. It returns one on success or zero if the signature is invalid or
- * on error. */
+/* ECDSA_do_verify verifies that |sig| constitutes a valid signature by |key|
+ * of |digest|. It returns one on success or zero if the signature is invalid
+ * or on error. */
 OPENSSL_EXPORT int ECDSA_do_verify(const uint8_t *digest, size_t digest_len,
                                    const ECDSA_SIG *sig, EC_KEY *key);
 
diff --git a/include/openssl/err.h b/include/openssl/err.h
index 100d608..40361d7 100644
--- a/include/openssl/err.h
+++ b/include/openssl/err.h
@@ -300,8 +300,8 @@
   ERR_put_error(ERR_LIB_##library, 0, reason, __FILE__, __LINE__)
 
 /* OPENSSL_PUT_SYSTEM_ERROR is used by OpenSSL code to add an error from the
- * operating system to the error queue. */
-/* TODO(fork): include errno. */
+ * operating system to the error queue.
+ * TODO(fork): include errno. */
 #define OPENSSL_PUT_SYSTEM_ERROR() \
   ERR_put_error(ERR_LIB_SYS, 0, 0, __FILE__, __LINE__);
 
diff --git a/include/openssl/evp.h b/include/openssl/evp.h
index 99b147e..095a498 100644
--- a/include/openssl/evp.h
+++ b/include/openssl/evp.h
@@ -664,7 +664,11 @@
 OPENSSL_EXPORT const EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_find(ENGINE **pengine,
                                                               int nid);
 
-/* TODO(fork): move to PEM? */
+/* EVP_PKEY_asn1_find_str returns an |EVP_PKEY_ASN1_METHOD| by matching values
+ * of the |len| bytes at |name|. For example, if name equals "EC" then it will
+ * return an ECC method. The |pengine| argument is ignored.
+ *
+ * TODO(fork): move to PEM? */
 OPENSSL_EXPORT const EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_find_str(
     ENGINE **pengine, const char *name, size_t len);
 
diff --git a/include/openssl/obj.h b/include/openssl/obj.h
index 956bbe9..32a4894 100644
--- a/include/openssl/obj.h
+++ b/include/openssl/obj.h
@@ -125,7 +125,7 @@
 /* OBJ_nid2sn returns the short name for |nid|, or NULL if |nid| is unknown. */
 OPENSSL_EXPORT const char *OBJ_nid2sn(int nid);
 
-/* OBJ_nid2sn returns the long name for |nid|, or NULL if |nid| is unknown. */
+/* OBJ_nid2ln returns the long name for |nid|, or NULL if |nid| is unknown. */
 OPENSSL_EXPORT const char *OBJ_nid2ln(int nid);
 
 /* OBJ_nid2cbb writes |nid| as an ASN.1 OBJECT IDENTIFIER to |out|. It returns
diff --git a/include/openssl/ssl.h b/include/openssl/ssl.h
index acdb984..e3be5cf 100644
--- a/include/openssl/ssl.h
+++ b/include/openssl/ssl.h
@@ -259,7 +259,7 @@
  * descriptor then it returns -1. */
 OPENSSL_EXPORT int SSL_get_wfd(const SSL *ssl);
 
-/* SSL_set_wfd configures |ssl| to read from and write to |fd|. It returns one
+/* SSL_set_fd configures |ssl| to read from and write to |fd|. It returns one
  * on success and zero on allocation error. The caller retains ownership of
  * |fd|. */
 OPENSSL_EXPORT int SSL_set_fd(SSL *ssl, int fd);
@@ -1181,13 +1181,13 @@
  * |str| as a cipher string. It returns one on success and zero on failure. */
 OPENSSL_EXPORT int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str);
 
-/* SSL_CTX_set_cipher_list configures the TLS 1.0+ cipher list for |ctx|,
+/* SSL_CTX_set_cipher_list_tls10 configures the TLS 1.0+ cipher list for |ctx|,
  * evaluating |str| as a cipher string. It returns one on success and zero on
  * failure. If set, servers will use this cipher suite list for TLS 1.0 or
  * higher. */
 OPENSSL_EXPORT int SSL_CTX_set_cipher_list_tls10(SSL_CTX *ctx, const char *str);
 
-/* SSL_CTX_set_cipher_list configures the TLS 1.1+ cipher list for |ctx|,
+/* SSL_CTX_set_cipher_list_tls11 configures the TLS 1.1+ cipher list for |ctx|,
  * evaluating |str| as a cipher string. It returns one on success and zero on
  * failure. If set, servers will use this cipher suite list for TLS 1.1 or
  * higher. */
@@ -2821,10 +2821,10 @@
 #define SSL_CB_HANDSHAKE_START 0x10
 #define SSL_CB_HANDSHAKE_DONE 0x20
 
-/* SSL_set_info_callback configures a callback to be run when various events
- * occur during a connection's lifetime. The |type| argumentj determines the
- * type of event and the meaning of the |value| argument. Callbacks must ignore
- * unexpected |type| values.
+/* SSL_CTX_set_info_callback configures a callback to be run when various
+ * events occur during a connection's lifetime. The |type| argumentj determines
+ * the type of event and the meaning of the |value| argument. Callbacks must
+ * ignore unexpected |type| values.
  *
  * |SSL_CB_READ_ALERT| is signaled for each alert received, warning or fatal.
  * The |value| argument is a 16-bit value where the alert level (either
@@ -2937,9 +2937,9 @@
 /* SSLv23_method calls |TLS_method|. */
 OPENSSL_EXPORT const SSL_METHOD *SSLv23_method(void);
 
-/* Version-specific methods behave exactly like |TLS_method| and |DTLS_method|
- * except they also call |SSL_CTX_set_min_version| and |SSL_CTX_set_max_version|
- * to lock connections to that protocol version. */
+/* These version-specific methods behave exactly like |TLS_method| and
+ * |DTLS_method| except they also call |SSL_CTX_set_min_version| and
+ * |SSL_CTX_set_max_version| to lock connections to that protocol version. */
 OPENSSL_EXPORT const SSL_METHOD *SSLv3_method(void);
 OPENSSL_EXPORT const SSL_METHOD *TLSv1_method(void);
 OPENSSL_EXPORT const SSL_METHOD *TLSv1_1_method(void);
@@ -2947,7 +2947,7 @@
 OPENSSL_EXPORT const SSL_METHOD *DTLSv1_method(void);
 OPENSSL_EXPORT const SSL_METHOD *DTLSv1_2_method(void);
 
-/* Client- and server-specific methods call their corresponding generic
+/* These client- and server-specific methods call their corresponding generic
  * methods. */
 OPENSSL_EXPORT const SSL_METHOD *SSLv23_server_method(void);
 OPENSSL_EXPORT const SSL_METHOD *SSLv23_client_method(void);
@@ -3313,7 +3313,8 @@
 #define SSL_get_state(ssl) SSL_state(ssl)
 
 /* SSL_state_string returns the current state of the handshake state machine as
- * a six-letter string. Use |SSL_state_string */
+ * a six-letter string. Use |SSL_state_string_long| for a more intelligible
+ * string. */
 OPENSSL_EXPORT const char *SSL_state_string(const SSL *ssl);
 
 /* SSL_set_shutdown causes |ssl| to behave as if the shutdown bitmask (see
diff --git a/util/doc.go b/util/doc.go
index ce7a3e8..7d15d9b 100644
--- a/util/doc.go
+++ b/util/doc.go
@@ -388,6 +388,19 @@
 			if last := len(section.Decls) - 1; len(name) == 0 && len(comment) == 0 && last >= 0 {
 				section.Decls[last].Decl += "\n" + decl
 			} else {
+				// As a matter of style, comments should start
+				// with the name of the thing that they are
+				// commenting on. We make an exception here for
+				// #defines (because we often have blocks of
+				// them) and collective comments, which are
+				// detected by starting with “The” or “These”.
+				if len(comment) > 0 &&
+					!strings.HasPrefix(comment[0], name) &&
+					!strings.HasPrefix(decl, "#define ") &&
+					!strings.HasPrefix(comment[0], "The ") &&
+					!strings.HasPrefix(comment[0], "These ") {
+					return nil, fmt.Errorf("Comment for %q doesn't seem to match just above %s:%d\n", name, path, lineNo)
+				}
 				anchor := sanitizeAnchor(name)
 				// TODO(davidben): Enforce uniqueness. This is
 				// skipped because #ifdefs currently result in