Document ASN1_NULL.

This starts expanding out the DECLARE_* macros in asn1.h. It also
documents some ways in which ASN1_NULL is odd.

Bug: 426
Change-Id: Ie166861d91ce78901c76b85de79dcc683e480275
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/49909
Reviewed-by: Adam Langley <agl@google.com>

include/openssl/asn1.h

@@ -830,6 +830,36 @@ OPENSSL_EXPORT int ASN1_TIME_set_string(ASN1_TIME *s, const char *str);
 // TODO(davidben): Expand and document function prototypes generated in macros.
 
 
+// NULL values.
+//
+// This library represents the ASN.1 NULL value by a non-NULL pointer to the
+// opaque type |ASN1_NULL|. An omitted OPTIONAL ASN.1 NULL value is a NULL
+// pointer. Unlike other pointer types, it is not necessary to free |ASN1_NULL|
+// pointers, but it is safe to do so.
+
+// ASN1_NULL_new returns an opaque, non-NULL pointer. It is safe to call
+// |ASN1_NULL_free| on the result, but not necessary.
+OPENSSL_EXPORT ASN1_NULL *ASN1_NULL_new(void);
+
+// ASN1_NULL_free does nothing.
+OPENSSL_EXPORT void ASN1_NULL_free(ASN1_NULL *null);
+
+// d2i_ASN1_NULL parses a DER-encoded ASN.1 NULL value from up to |len| bytes
+// at |*inp|, as described in |d2i_SAMPLE|.
+//
+// TODO(https://crbug.com/boringssl/354): This function currently also accepts
+// BER, but this will be removed in the future.
+OPENSSL_EXPORT ASN1_NULL *d2i_ASN1_NULL(ASN1_NULL **out, const uint8_t **inp,
+                                        long len);
+
+// i2d_ASN1_NULL marshals |in| as a DER-encoded ASN.1 NULL value, as described
+// in |i2d_SAMPLE|.
+OPENSSL_EXPORT int i2d_ASN1_NULL(const ASN1_NULL *in, uint8_t **outp);
+
+// ASN1_NULL is an |ASN1_ITEM| with ASN.1 type NULL and C type |ASN1_NULL*|.
+DECLARE_ASN1_ITEM(ASN1_NULL)
+
+
 // Arbitrary elements.
 
 // An asn1_type_st (aka |ASN1_TYPE|) represents an arbitrary ASN.1 element,
@@ -1227,7 +1257,6 @@ OPENSSL_EXPORT int ASN1_OCTET_STRING_set(ASN1_OCTET_STRING *str,
 DECLARE_ASN1_FUNCTIONS_const(ASN1_VISIBLESTRING)
 DECLARE_ASN1_FUNCTIONS_const(ASN1_UNIVERSALSTRING)
 DECLARE_ASN1_FUNCTIONS_const(ASN1_UTF8STRING)
-DECLARE_ASN1_FUNCTIONS_const(ASN1_NULL)
 DECLARE_ASN1_FUNCTIONS_const(ASN1_BMPSTRING)
 
 DECLARE_ASN1_FUNCTIONS_name(ASN1_STRING, ASN1_PRINTABLE)