Have doc.go parse struct comments.

In code, structs that happened to have a '(' somewhere in their body
would cause the parser to go wrong. This change fixes that and updates
the comments on a number of structs.

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

include/openssl/buf.h

@@ -67,7 +67,7 @@ extern "C" {
 /* Memory and string functions, see also mem.h. */
 
 
-/* BUF_MEM is a generic buffer object used by OpenSSL. */
+/* buf_mem_st (aka |BUF_MEM|) is a generic buffer object used by OpenSSL. */
 struct buf_mem_st {
   size_t length; /* current number of bytes */
   char *data;

include/openssl/dsa.h

@@ -128,7 +128,7 @@ OPENSSL_EXPORT int DSA_generate_key(DSA *dsa);
 
 /* Signatures. */
 
-/* DSA_SIG contains a DSA signature as a pair of integers. */
+/* DSA_SIG_st (aka |DSA_SIG|) contains a DSA signature as a pair of integers. */
 typedef struct DSA_SIG_st {
   BIGNUM *r, *s;
 } DSA_SIG;

include/openssl/err.h

@@ -368,7 +368,7 @@ struct err_error_st {
 /* ERR_NUM_ERRORS is the limit of the number of errors in the queue. */
 #define ERR_NUM_ERRORS 16
 
-/* ERR_STATE contains the per-thread, error queue. */
+/* err_state_st (aka |ERR_STATE|) contains the per-thread, error queue. */
 typedef struct err_state_st {
   /* errors contains the ERR_NUM_ERRORS most recent errors, organised as a ring
    * buffer. */

include/openssl/ssl.h

@@ -2359,8 +2359,8 @@ OPENSSL_EXPORT void (*SSL_CTX_get_channel_id_cb(SSL_CTX *ctx))(
  *
  * See RFC 5764. */
 
-/* An SRTP_PROTECTION_PROFILE is an SRTP profile for use with the use_srtp
- * extension. */
+/* srtp_protection_profile_st (aka |SRTP_PROTECTION_PROFILE|) is an SRTP
+ * profile for use with the use_srtp extension. */
 struct srtp_protection_profile_st {
   const char *name;
   unsigned long id;
@@ -3487,6 +3487,8 @@ struct ssl_cipher_preference_list_st {
   uint8_t *in_group_flags;
 };
 
+/* ssl_ctx_st (aka |SSL_CTX|) contains configuration common to several SSL
+ * connections. */
 struct ssl_ctx_st {
   const SSL_PROTOCOL_METHOD *method;
 

util/doc.go

@@ -203,15 +203,28 @@ func getNameFromDecl(decl string) (string, bool) {
 	for strings.HasPrefix(decl, "#if") || strings.HasPrefix(decl, "#elif") {
 		decl = skipLine(decl)
 	}
-	if strings.HasPrefix(decl, "struct ") {
+
+	if strings.HasPrefix(decl, "typedef ") {
 		return "", false
 	}
-	if strings.HasPrefix(decl, "#define ") {
-		// This is a preprocessor #define. The name is the next symbol.
-		decl = strings.TrimPrefix(decl, "#define ")
+
+	for _, prefix := range []string{"struct ", "enum ", "#define "} {
+		if !strings.HasPrefix(decl, prefix) {
+			continue
+		}
+
+		decl = strings.TrimPrefix(decl, prefix)
+
 		for len(decl) > 0 && decl[0] == ' ' {
 			decl = decl[1:]
 		}
+
+		// struct and enum types can be the return type of a
+		// function.
+		if prefix[0] != '#' && strings.Index(decl, "{") == -1 {
+			break
+		}
+
 		i := strings.IndexAny(decl, "( ")
 		if i < 0 {
 			return "", false