Various documentation fixes. Add some missing headers and ensure each header has a short description. doc.go gets confused at declarations that break before the first (, so avoid doing that. Also skip a/an/deprecated: in markupFirstWord and process pipe words in the table of contents. Change-Id: Ia08ec5ae8e496dd617e377e154eeea74f4abf435 Reviewed-on: https://boringssl-review.googlesource.com/2839 Reviewed-by: Adam Langley <agl@google.com>
diff --git a/include/openssl/base64.h b/include/openssl/base64.h index 44f91eb..7aee990 100644 --- a/include/openssl/base64.h +++ b/include/openssl/base64.h
@@ -99,8 +99,8 @@ /* EVP_EncodeBlock encodes |src_len| bytes from |src| and writes the * result to |dst| with a trailing NUL. It returns the number of bytes * written, not including this trailing NUL. */ -OPENSSL_EXPORT size_t - EVP_EncodeBlock(uint8_t *dst, const uint8_t *src, size_t src_len); +OPENSSL_EXPORT size_t EVP_EncodeBlock(uint8_t *dst, const uint8_t *src, + size_t src_len); /* EVP_EncodedLength sets |*out_len| to the number of bytes that will be needed * to call |EVP_EncodeBlock| on an input of length |len|. This includes the @@ -158,6 +158,7 @@ OPENSSL_EXPORT int EVP_DecodeBlock(uint8_t *dst, const uint8_t *src, size_t src_len); + struct evp_encode_ctx_st { unsigned num; /* number saved in a partial encode/decode */ unsigned length; /* The length is either the output line length
diff --git a/include/openssl/buf.h b/include/openssl/buf.h index 1248214..0a0a9b8 100644 --- a/include/openssl/buf.h +++ b/include/openssl/buf.h
@@ -64,6 +64,9 @@ #endif +/* Memory and string functions, see also mem.h. */ + + /* BUF_MEM is a generic buffer object used by OpenSSL. */ struct buf_mem_st { size_t length; /* current number of bytes */
diff --git a/include/openssl/bytestring.h b/include/openssl/bytestring.h index d5e6cf9..2bff3f5 100644 --- a/include/openssl/bytestring.h +++ b/include/openssl/bytestring.h
@@ -317,6 +317,7 @@ * error. */ OPENSSL_EXPORT int CBB_add_asn1_uint64(CBB *cbb, uint64_t value); + #if defined(__cplusplus) } /* extern C */ #endif
diff --git a/include/openssl/cpu.h b/include/openssl/cpu.h index 5f60754..81121f1 100644 --- a/include/openssl/cpu.h +++ b/include/openssl/cpu.h
@@ -68,6 +68,9 @@ #endif +/* Runtime CPU feature support */ + + #if defined(OPENSSL_X86) || defined(OPENSSL_X86_64) /* OPENSSL_ia32cap_P contains the Intel CPUID bits when running on an x86 or * x86-64 system.
diff --git a/include/openssl/des.h b/include/openssl/des.h index 748f1c8..1f0dbad 100644 --- a/include/openssl/des.h +++ b/include/openssl/des.h
@@ -64,6 +64,9 @@ #endif +/* DES. */ + + typedef struct DES_cblock_st { uint8_t bytes[8]; } DES_cblock;
diff --git a/include/openssl/digest.h b/include/openssl/digest.h index 682f333..95a35e7 100644 --- a/include/openssl/digest.h +++ b/include/openssl/digest.h
@@ -237,8 +237,8 @@ /* EVP_MD_CTX_test_flags returns the AND of |flags| and the flags member of * |ctx|. */ -OPENSSL_EXPORT uint32_t - EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, uint32_t flags); +OPENSSL_EXPORT uint32_t EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, + uint32_t flags); struct evp_md_pctx_ops;
diff --git a/include/openssl/ec.h b/include/openssl/ec.h index 7b50caa..86d7de7 100644 --- a/include/openssl/ec.h +++ b/include/openssl/ec.h
@@ -75,6 +75,9 @@ #endif +/* Low-level operations on elliptic curves. */ + + typedef struct ec_group_st EC_GROUP; typedef struct ec_point_st EC_POINT;
diff --git a/include/openssl/ecdh.h b/include/openssl/ecdh.h index e97d757..04cd38a 100644 --- a/include/openssl/ecdh.h +++ b/include/openssl/ecdh.h
@@ -76,6 +76,9 @@ #endif +/* Elliptic curve Diffie-Hellman. */ + + /* ECDH_compute_key calculates the shared key between |pub_key| and |priv_key|. * If |KDF| is not NULL, then it is called with the bytes of the shared key and * the parameter |out|. When |KDF| returns, the value of |*outlen| becomes the
diff --git a/include/openssl/ecdsa.h b/include/openssl/ecdsa.h index ec4df0f..f3ff49f 100644 --- a/include/openssl/ecdsa.h +++ b/include/openssl/ecdsa.h
@@ -62,7 +62,7 @@ #endif -/* DSA contains functions for signing and verifing with the Digital Signature +/* ECDSA contains functions for signing and verifying with the Digital Signature * Algorithm over elliptic curves. */
diff --git a/include/openssl/err.h b/include/openssl/err.h index 8e99767..18a43ce 100644 --- a/include/openssl/err.h +++ b/include/openssl/err.h
@@ -186,9 +186,10 @@ * they return the most recent error. */ OPENSSL_EXPORT uint32_t ERR_peek_last_error(void); OPENSSL_EXPORT uint32_t ERR_peek_last_error_line(const char **file, int *line); -OPENSSL_EXPORT uint32_t - ERR_peek_last_error_line_data(const char **file, int *line, - const char **data, int *flags); +OPENSSL_EXPORT uint32_t ERR_peek_last_error_line_data(const char **file, + int *line, + const char **data, + int *flags); /* ERR_error_string generates a human-readable string representing * |packed_error|, places it at |buf| (which must be at least
diff --git a/include/openssl/mem.h b/include/openssl/mem.h index 293e04b..3bd01c0 100644 --- a/include/openssl/mem.h +++ b/include/openssl/mem.h
@@ -65,7 +65,9 @@ #endif -/* OpenSSL has, historically, had a complex set of malloc debugging options. +/* Memory and string functions, see also buf.h. + * + * OpenSSL has, historically, had a complex set of malloc debugging options. * However, that was written in a time before Valgrind and ASAN. Since we now * have those tools, the OpenSSL allocation functions are simply macros around * the standard memory functions. */
diff --git a/include/openssl/rc4.h b/include/openssl/rc4.h index 4c13117..727b474 100644 --- a/include/openssl/rc4.h +++ b/include/openssl/rc4.h
@@ -64,6 +64,9 @@ #endif +/* RC4. */ + + typedef struct rc4_key_st { uint32_t x, y; /* data is sometimes used as an array of 32-bit values and sometimes as 8-bit
diff --git a/include/openssl/sha.h b/include/openssl/sha.h index 1f321fc..5b363ee 100644 --- a/include/openssl/sha.h +++ b/include/openssl/sha.h
@@ -64,7 +64,7 @@ #endif -/* SHA-1. */ +/* The SHA family of hash functions (SHA-1 and SHA-2). */ /* SHA_CBLOCK is the block size of SHA-1. */
diff --git a/include/openssl/ssl.h b/include/openssl/ssl.h index 7b79904..68c3535 100644 --- a/include/openssl/ssl.h +++ b/include/openssl/ssl.h
@@ -2030,9 +2030,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 they - * also call SSL_CTX_set_min_version and SSL_CTX_set_max_version to lock - * connections to that protocol version. */ +/* 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);
diff --git a/include/openssl/time_support.h b/include/openssl/time_support.h index 051c691..d03a99d 100644 --- a/include/openssl/time_support.h +++ b/include/openssl/time_support.h
@@ -67,6 +67,9 @@ #endif +/* Wrapper functions for time functions. */ + + /* OPENSSL_gmtime wraps |gmtime_r|. See the manual page for that function. */ struct tm *OPENSSL_gmtime(const time_t *timer, struct tm *result);
diff --git a/util/doc.config b/util/doc.config index 4b5f3b1..62db0f3 100644 --- a/util/doc.config +++ b/util/doc.config
@@ -6,6 +6,7 @@ "include/openssl/base64.h", "include/openssl/bio.h", "include/openssl/buf.h", + "include/openssl/bytestring.h", "include/openssl/err.h", "include/openssl/cpu.h", "include/openssl/ex_data.h", @@ -41,6 +42,7 @@ "Headers": [ "include/openssl/digest.h", "include/openssl/cipher.h", + "include/openssl/aead.h", "include/openssl/evp.h" ] }]
diff --git a/util/doc.go b/util/doc.go index 43d9b90..7c96af8 100644 --- a/util/doc.go +++ b/util/doc.go
@@ -420,9 +420,17 @@ } func markupFirstWord(s template.HTML) template.HTML { - i := strings.Index(string(s), " ") - if i > 0 { - return "<span class=\"first-word\">" + s[:i] + "</span>" + s[i:] + start := 0 +again: + end := strings.Index(string(s[start:]), " ") + if end > 0 { + end += start + w := strings.ToLower(string(s[start:end])) + if w == "a" || w == "an" || w == "deprecated:" { + start = end + 1 + goto again + } + return s[:start] + "<span class=\"first-word\">" + s[start:end] + "</span>" + s[end:] } return s } @@ -445,7 +453,7 @@ "markupFirstWord": markupFirstWord, "newlinesToBR": newlinesToBR, }) - headerTmpl, err := headerTmpl.Parse(`<!DOCTYPE html5> + headerTmpl, err := headerTmpl.Parse(`<!DOCTYPE html> <html> <head> <title>BoringSSL - {{.Name}}</title> @@ -462,7 +470,7 @@ <ol> {{range .Sections}} {{if not .IsPrivate}} - {{if .Preamble}}<li class="header"><a href="#section-{{.Num}}">{{.Preamble | firstSentence}}</a></li>{{end}} + {{if .Preamble}}<li class="header"><a href="#section-{{.Num}}">{{.Preamble | firstSentence | html | markupPipeWords}}</a></li>{{end}} {{range .Decls}} {{if .Name}}<li><a href="#decl-{{.Num}}"><tt>{{.Name}}</tt></a></li>{{end}} {{end}}