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}}
