Fix up several comments and detect problems in the future.

This change fixes up several comments (many of which were spotted by
Kenny Root) and also changes doc.go to detect cases where comments don't
start with the correct word. (This is a common error.)

Since we have docs builders now, these errors will be found
automatically in the future.

Change-Id: I58c6dd4266bf3bd4ec748763c8762b1a67ae5ab3
Reviewed-on: https://boringssl-review.googlesource.com/6440
Reviewed-by: Adam Langley <agl@google.com>

11 files changed, 60 insertions, 40 deletions

diff --git a/crypto/poly1305/poly1305_test.txt b/crypto/poly1305/poly1305_test.txt
index 2a92c125..ad40699e 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 16676c57..4f822e8c 100644
--- a/include/openssl/aead.h
+++ b/include/openssl/aead.h
@@ -134,7 +134,7 @@ OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_key_wrap(void);
  * 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 44de50f2..8d475949 100644
--- a/include/openssl/bio.h
+++ b/include/openssl/bio.h
@@ -728,10 +728,11 @@ OPENSSL_EXPORT int BIO_zero_copy_get_write_buf_done(BIO* bio,
 
 /* 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 c9bdb1e4..1a3958f0 100644
--- a/include/openssl/bn.h
+++ b/include/openssl/bn.h
@@ -532,7 +532,7 @@ OPENSSL_EXPORT int BN_mod_sub_quick(BIGNUM *r, const BIGNUM *a, const BIGNUM *b,
 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 @@ OPENSSL_EXPORT int BN_mod_exp2_mont(BIGNUM *r, const BIGNUM *a1,
  * 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 a4e79ddd..fb7171f0 100644
--- a/include/openssl/cipher.h
+++ b/include/openssl/cipher.h
@@ -91,17 +91,6 @@ OPENSSL_EXPORT const EVP_CIPHER *EVP_aes_256_ctr(void);
 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 @@ OPENSSL_EXPORT int EVP_add_cipher_alias(const char *a, const char *b);
  * |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 b7f15c49..f3f68eb2 100644
--- a/include/openssl/ecdsa.h
+++ b/include/openssl/ecdsa.h
@@ -106,14 +106,14 @@ OPENSSL_EXPORT ECDSA_SIG *ECDSA_SIG_new(void);
 /* 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 100d608b..40361d79 100644
--- a/include/openssl/err.h
+++ b/include/openssl/err.h
@@ -300,8 +300,8 @@ OPENSSL_EXPORT void ERR_clear_system_error(void);
   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 99b147e1..095a498f 100644
--- a/include/openssl/evp.h
+++ b/include/openssl/evp.h
@@ -664,7 +664,11 @@ OPENSSL_EXPORT void EVP_cleanup(void);
 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 956bbe94..32a48948 100644
--- a/include/openssl/obj.h
+++ b/include/openssl/obj.h
@@ -125,7 +125,7 @@ OPENSSL_EXPORT const ASN1_OBJECT *OBJ_nid2obj(int nid);
 /* 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 acdb984e..e3be5cf8 100644
--- a/include/openssl/ssl.h
+++ b/include/openssl/ssl.h
@@ -259,7 +259,7 @@ OPENSSL_EXPORT int SSL_get_rfd(const SSL *ssl);
  * 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 @@ OPENSSL_EXPORT int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher,
  * |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 @@ OPENSSL_EXPORT void SSL_CTX_set_dos_protection_cb(
 #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 @@ OPENSSL_EXPORT const char *SSL_COMP_get_name(const COMP_METHOD *comp);
 /* 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 *TLSv1_2_method(void);
 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 @@ OPENSSL_EXPORT int SSL_state(const SSL *ssl);
 #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 ce7a3e80..7d15d9ba 100644
--- a/util/doc.go
+++ b/util/doc.go
@@ -388,6 +388,19 @@ func (config *Config) parseHeader(path string) (*HeaderFile, error) {
 			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