Tidy up docs for #defines.
This removes the special-case for #defines in doc.go.
Change-Id: I6bf750485a94ad28c3975644c74a17c550bb3224
Reviewed-on: https://boringssl-review.googlesource.com/31505
Reviewed-by: Adam Langley <agl@google.com>
diff --git a/include/openssl/bio.h b/include/openssl/bio.h
index adb641b..dcf8ab7 100644
--- a/include/openssl/bio.h
+++ b/include/openssl/bio.h
@@ -677,26 +677,49 @@
OPENSSL_EXPORT int BIO_get_init(BIO *bio);
// These are values of the |cmd| argument to |BIO_ctrl|.
-#define BIO_CTRL_RESET 1 // opt - rewind/zero etc
-#define BIO_CTRL_EOF 2 // opt - are we at the eof
-#define BIO_CTRL_INFO 3 // opt - extra tit-bits
-#define BIO_CTRL_SET 4 // man - set the 'IO' type
-#define BIO_CTRL_GET 5 // man - get the 'IO' type
-#define BIO_CTRL_PUSH 6
-#define BIO_CTRL_POP 7
-#define BIO_CTRL_GET_CLOSE 8 // man - set the 'close' on free
-#define BIO_CTRL_SET_CLOSE 9 // man - set the 'close' on free
-#define BIO_CTRL_PENDING 10 // opt - is their more data buffered
-#define BIO_CTRL_FLUSH 11 // opt - 'flush' buffered output
-#define BIO_CTRL_WPENDING 13 // opt - number of bytes still to write
-// callback is int cb(BIO *bio,state,ret);
-#define BIO_CTRL_SET_CALLBACK 14 // opt - set callback function
-#define BIO_CTRL_GET_CALLBACK 15 // opt - set callback function
-#define BIO_CTRL_SET_FILENAME 30 // BIO_s_file special
-// BIO_CTRL_DUP is never used, but exists to allow code to compile more
-// easily.
-#define BIO_CTRL_DUP 12
+// BIO_CTRL_RESET implements |BIO_reset|. The arguments are unused.
+#define BIO_CTRL_RESET 1
+
+// BIO_CTRL_EOF implements |BIO_eof|. The arguments are unused.
+#define BIO_CTRL_EOF 2
+
+// BIO_CTRL_INFO is a legacy command that returns information specific to the
+// type of |BIO|. It is not safe to call generically and should not be
+// implemented in new |BIO| types.
+#define BIO_CTRL_INFO 3
+
+// BIO_CTRL_GET_CLOSE returns the close flag set by |BIO_CTRL_SET_CLOSE|. The
+// arguments are unused.
+#define BIO_CTRL_GET_CLOSE 8
+
+// BIO_CTRL_SET_CLOSE implements |BIO_set_close|. The |larg| argument is the
+// close flag.
+#define BIO_CTRL_SET_CLOSE 9
+
+// BIO_CTRL_PENDING implements |BIO_pending|. The arguments are unused.
+#define BIO_CTRL_PENDING 10
+
+// BIO_CTRL_FLUSH implements |BIO_flush|. The arguments are unused.
+#define BIO_CTRL_FLUSH 11
+
+// BIO_CTRL_WPENDING implements |BIO_wpending|. The arguments are unused.
+#define BIO_CTRL_WPENDING 13
+
+// BIO_CTRL_SET_CALLBACK sets an informational callback of type
+// int cb(BIO *bio, int state, int ret)
+#define BIO_CTRL_SET_CALLBACK 14
+
+// BIO_CTRL_GET_CALLBACK returns the callback set by |BIO_CTRL_SET_CALLBACK|.
+#define BIO_CTRL_GET_CALLBACK 15
+
+// The following are never used, but are defined to aid porting existing code.
+#define BIO_CTRL_SET 4
+#define BIO_CTRL_GET 5
+#define BIO_CTRL_PUSH 6
+#define BIO_CTRL_POP 7
+#define BIO_CTRL_DUP 12
+#define BIO_CTRL_SET_FILENAME 30
// Deprecated functions.
@@ -733,8 +756,8 @@
#define BIO_FLAGS_RWS (BIO_FLAGS_READ | BIO_FLAGS_WRITE | BIO_FLAGS_IO_SPECIAL)
#define BIO_FLAGS_SHOULD_RETRY 0x08
#define BIO_FLAGS_BASE64_NO_NL 0x100
-// This is used with memory BIOs: it means we shouldn't free up or change the
-// data in any way.
+// BIO_FLAGS_MEM_RDONLY is used with memory BIOs. It means we shouldn't free up
+// or change the data in any way.
#define BIO_FLAGS_MEM_RDONLY 0x200
// These are the 'types' of BIOs
@@ -762,7 +785,7 @@
#define BIO_TYPE_ASN1 (22 | 0x0200) // filter
#define BIO_TYPE_COMP (23 | 0x0200) // filter
-// |BIO_TYPE_DESCRIPTOR| denotes that the |BIO| responds to the |BIO_C_SET_FD|
+// BIO_TYPE_DESCRIPTOR denotes that the |BIO| responds to the |BIO_C_SET_FD|
// (|BIO_set_fd|) and |BIO_C_GET_FD| (|BIO_get_fd|) control hooks.
#define BIO_TYPE_DESCRIPTOR 0x0100 // socket, fd, connect or accept
#define BIO_TYPE_FILTER 0x0200
@@ -809,61 +832,61 @@
size_t num_read, num_write;
};
-#define BIO_C_SET_CONNECT 100
-#define BIO_C_DO_STATE_MACHINE 101
-#define BIO_C_SET_NBIO 102
-#define BIO_C_SET_PROXY_PARAM 103
-#define BIO_C_SET_FD 104
-#define BIO_C_GET_FD 105
-#define BIO_C_SET_FILE_PTR 106
-#define BIO_C_GET_FILE_PTR 107
-#define BIO_C_SET_FILENAME 108
-#define BIO_C_SET_SSL 109
-#define BIO_C_GET_SSL 110
-#define BIO_C_SET_MD 111
-#define BIO_C_GET_MD 112
-#define BIO_C_GET_CIPHER_STATUS 113
-#define BIO_C_SET_BUF_MEM 114
-#define BIO_C_GET_BUF_MEM_PTR 115
-#define BIO_C_GET_BUFF_NUM_LINES 116
-#define BIO_C_SET_BUFF_SIZE 117
-#define BIO_C_SET_ACCEPT 118
-#define BIO_C_SSL_MODE 119
-#define BIO_C_GET_MD_CTX 120
-#define BIO_C_GET_PROXY_PARAM 121
-#define BIO_C_SET_BUFF_READ_DATA 122 // data to read first
-#define BIO_C_GET_ACCEPT 124
-#define BIO_C_SET_SSL_RENEGOTIATE_BYTES 125
-#define BIO_C_GET_SSL_NUM_RENEGOTIATES 126
-#define BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT 127
-#define BIO_C_FILE_SEEK 128
-#define BIO_C_GET_CIPHER_CTX 129
-#define BIO_C_SET_BUF_MEM_EOF_RETURN 130 //return end of input value
-#define BIO_C_SET_BIND_MODE 131
-#define BIO_C_GET_BIND_MODE 132
-#define BIO_C_FILE_TELL 133
-#define BIO_C_GET_SOCKS 134
-#define BIO_C_SET_SOCKS 135
+#define BIO_C_SET_CONNECT 100
+#define BIO_C_DO_STATE_MACHINE 101
+#define BIO_C_SET_NBIO 102
+#define BIO_C_SET_PROXY_PARAM 103
+#define BIO_C_SET_FD 104
+#define BIO_C_GET_FD 105
+#define BIO_C_SET_FILE_PTR 106
+#define BIO_C_GET_FILE_PTR 107
+#define BIO_C_SET_FILENAME 108
+#define BIO_C_SET_SSL 109
+#define BIO_C_GET_SSL 110
+#define BIO_C_SET_MD 111
+#define BIO_C_GET_MD 112
+#define BIO_C_GET_CIPHER_STATUS 113
+#define BIO_C_SET_BUF_MEM 114
+#define BIO_C_GET_BUF_MEM_PTR 115
+#define BIO_C_GET_BUFF_NUM_LINES 116
+#define BIO_C_SET_BUFF_SIZE 117
+#define BIO_C_SET_ACCEPT 118
+#define BIO_C_SSL_MODE 119
+#define BIO_C_GET_MD_CTX 120
+#define BIO_C_GET_PROXY_PARAM 121
+#define BIO_C_SET_BUFF_READ_DATA 122 // data to read first
+#define BIO_C_GET_ACCEPT 124
+#define BIO_C_SET_SSL_RENEGOTIATE_BYTES 125
+#define BIO_C_GET_SSL_NUM_RENEGOTIATES 126
+#define BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT 127
+#define BIO_C_FILE_SEEK 128
+#define BIO_C_GET_CIPHER_CTX 129
+#define BIO_C_SET_BUF_MEM_EOF_RETURN 130 // return end of input value
+#define BIO_C_SET_BIND_MODE 131
+#define BIO_C_GET_BIND_MODE 132
+#define BIO_C_FILE_TELL 133
+#define BIO_C_GET_SOCKS 134
+#define BIO_C_SET_SOCKS 135
-#define BIO_C_SET_WRITE_BUF_SIZE 136 // for BIO_s_bio
-#define BIO_C_GET_WRITE_BUF_SIZE 137
-#define BIO_C_GET_WRITE_GUARANTEE 140
-#define BIO_C_GET_READ_REQUEST 141
-#define BIO_C_SHUTDOWN_WR 142
-#define BIO_C_NREAD0 143
-#define BIO_C_NREAD 144
-#define BIO_C_NWRITE0 145
-#define BIO_C_NWRITE 146
-#define BIO_C_RESET_READ_REQUEST 147
-#define BIO_C_SET_MD_CTX 148
+#define BIO_C_SET_WRITE_BUF_SIZE 136 // for BIO_s_bio
+#define BIO_C_GET_WRITE_BUF_SIZE 137
+#define BIO_C_GET_WRITE_GUARANTEE 140
+#define BIO_C_GET_READ_REQUEST 141
+#define BIO_C_SHUTDOWN_WR 142
+#define BIO_C_NREAD0 143
+#define BIO_C_NREAD 144
+#define BIO_C_NWRITE0 145
+#define BIO_C_NWRITE 146
+#define BIO_C_RESET_READ_REQUEST 147
+#define BIO_C_SET_MD_CTX 148
-#define BIO_C_SET_PREFIX 149
-#define BIO_C_GET_PREFIX 150
-#define BIO_C_SET_SUFFIX 151
-#define BIO_C_GET_SUFFIX 152
+#define BIO_C_SET_PREFIX 149
+#define BIO_C_GET_PREFIX 150
+#define BIO_C_SET_SUFFIX 151
+#define BIO_C_GET_SUFFIX 152
-#define BIO_C_SET_EX_ARG 153
-#define BIO_C_GET_EX_ARG 154
+#define BIO_C_SET_EX_ARG 153
+#define BIO_C_GET_EX_ARG 154
#if defined(__cplusplus)
