From 8162f6f58aa784e242941d1168fb8fc0618cf0a2 Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Thu, 9 Jun 2016 17:02:59 -0400 Subject: [PATCH] More API docs; small changes. Also fix typo noted on GitHub. Suppport typedef and #define to find-doc-nits Reviewed-by: Richard Levitte --- doc/crypto/ASN1_INTEGER_get_int64.pod | 1 + doc/crypto/BIO_ADDRINFO.pod | 9 +++----- doc/crypto/BIO_should_retry.pod | 2 +- doc/crypto/EC_KEY_new.pod | 2 +- doc/crypto/EVP_PKEY_encrypt.pod | 2 +- doc/crypto/X509_LOOKUP_hash_dir.pod | 3 ++- doc/crypto/X509_STORE_CTX_get_error.pod | 3 ++- doc/crypto/X509_STORE_CTX_new.pod | 6 ----- doc/crypto/d2i_PKCS8PrivateKey.pod | 4 ++-- doc/ssl/SSL_get_version.pod | 2 +- util/find-doc-nits.pl | 29 +++++++++++++++---------- 11 files changed, 32 insertions(+), 31 deletions(-) diff --git a/doc/crypto/ASN1_INTEGER_get_int64.pod b/doc/crypto/ASN1_INTEGER_get_int64.pod index 9299a51267..24e0f38003 100644 --- a/doc/crypto/ASN1_INTEGER_get_int64.pod +++ b/doc/crypto/ASN1_INTEGER_get_int64.pod @@ -2,6 +2,7 @@ =head1 NAME +ASN1_INTEGER_get_uint64, ASN1_INTEGER_set_uint64, ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_int64, ASN1_INTEGER_set, BN_to_ASN1_INTEGER, ASN1_INTEGER_to_BN, ASN1_ENUMERATED_get_int64, ASN1_ENUMERATED_get, ASN1_ENUMERATED_set_int64, ASN1_ENUMERATED_set, BN_to_ASN1_ENUMERATED, ASN1_ENUMERATED_to_BN, - ASN.1 INTEGER and ENUMERATED utilities =head1 SYNOPSIS diff --git a/doc/crypto/BIO_ADDRINFO.pod b/doc/crypto/BIO_ADDRINFO.pod index 1a3dd086ca..9ebf99a814 100644 --- a/doc/crypto/BIO_ADDRINFO.pod +++ b/doc/crypto/BIO_ADDRINFO.pod @@ -2,9 +2,10 @@ =head1 NAME -BIO_ADDRINFO, BIO_ADDRINFO_lookup, BIO_ADDRINFO_next, BIO_ADDRINFO_free, +BIO_ADDRINFO, BIO_ADDRINFO_next, BIO_ADDRINFO_free, BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol, -BIO_ADDRINFO_sockaddr, BIO_ADDRINFO_sockaddr_size, BIO_ADDRINFO_address +BIO_ADDRINFO_address, +BIO_lookup - BIO_ADDRINFO type and routines =head1 SYNOPSIS @@ -77,10 +78,6 @@ will leave an error indication on the OpenSSL error stack in that case. All other functions described here return 0 or B when the information they should return isn't available. -=head1 SEE ALSO - -L - =head1 COPYRIGHT Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/crypto/BIO_should_retry.pod b/doc/crypto/BIO_should_retry.pod index 162e768dc2..fc728ff9f2 100644 --- a/doc/crypto/BIO_should_retry.pod +++ b/doc/crypto/BIO_should_retry.pod @@ -2,7 +2,7 @@ =head1 NAME -BIO_should_retry, BIO_should_read, BIO_should_write, +BIO_should_read, BIO_should_write, BIO_should_io_special, BIO_retry_type, BIO_should_retry, BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry functions diff --git a/doc/crypto/EC_KEY_new.pod b/doc/crypto/EC_KEY_new.pod index 76c5ba3358..548165bc43 100644 --- a/doc/crypto/EC_KEY_new.pod +++ b/doc/crypto/EC_KEY_new.pod @@ -6,7 +6,7 @@ EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags, EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref, EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key, -EC_KEY_get_enc_flags, EC_KEY_set_enc_flags, EC_KEY_get_conv_form, +EC_KEY_get_conv_form, EC_KEY_set_conv_form, EC_KEY_set_asn1_flag, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates, EC_KEY_oct2key, EC_KEY_key2buf, EC_KEY_oct2priv, EC_KEY_priv2oct, diff --git a/doc/crypto/EVP_PKEY_encrypt.pod b/doc/crypto/EVP_PKEY_encrypt.pod index 9dc8499c61..d75f3f22cd 100644 --- a/doc/crypto/EVP_PKEY_encrypt.pod +++ b/doc/crypto/EVP_PKEY_encrypt.pod @@ -43,7 +43,7 @@ indicates the operation is not supported by the public key algorithm. =head1 EXAMPLE -Encrypt data using OAEP (for RSA keys). See also L or +Encrypt data using OAEP (for RSA keys). See also L or L for means to load a public key. You may also simply set 'eng = NULL;' to start with the default OpenSSL RSA implementation: diff --git a/doc/crypto/X509_LOOKUP_hash_dir.pod b/doc/crypto/X509_LOOKUP_hash_dir.pod index e9aafa3b98..08fa731238 100644 --- a/doc/crypto/X509_LOOKUP_hash_dir.pod +++ b/doc/crypto/X509_LOOKUP_hash_dir.pod @@ -113,7 +113,8 @@ hashed names for all files with .pem suffix in a given directory. =head1 SEE ALSO -L, L, +L, +L, L, L, L, diff --git a/doc/crypto/X509_STORE_CTX_get_error.pod b/doc/crypto/X509_STORE_CTX_get_error.pod index 26fcf607c3..d4163d7acf 100644 --- a/doc/crypto/X509_STORE_CTX_get_error.pod +++ b/doc/crypto/X509_STORE_CTX_get_error.pod @@ -61,7 +61,8 @@ needs to increment its reference count via L. Once such a I certificate is no longer needed it can be freed with L. -X509_STORE_CTX_get0_cert() returns the leaf certificate being verified. +X509_STORE_CTX_get0_cert() retrieves an internal pointer to the +certificate being verified by the B. X509_STORE_CTX_get1_chain() returns a complete validate chain if a previous call to X509_verify_cert() is successful. If the call to X509_verify_cert() diff --git a/doc/crypto/X509_STORE_CTX_new.pod b/doc/crypto/X509_STORE_CTX_new.pod index 7b9952cacc..1f4d410723 100644 --- a/doc/crypto/X509_STORE_CTX_new.pod +++ b/doc/crypto/X509_STORE_CTX_new.pod @@ -7,11 +7,9 @@ X509_STORE_CTX_init, X509_STORE_CTX_set0_trusted_stack, X509_STORE_CTX_set_cert, X509_STORE_CTX_set0_crls, X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain, X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param, -X509_STORE_CTX_get0_cert, X509_STORE_CTX_get0_untrusted, X509_STORE_CTX_set0_untrusted, X509_STORE_CTX_get_num_untrusted, X509_STORE_CTX_set_default, -X509_STORE_CTX_get_verify_cb, X509_STORE_CTX_set_verify, X509_STORE_CTX_get_verify - X509_STORE_CTX initialisation @@ -37,7 +35,6 @@ X509_STORE_CTX_get_verify - X509_STORE_CTX initialisation void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param); int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name); - X509 *X509_STORE_CTX_get0_cert(X509_STORE_CTX *ctx); STACK_OF(X509)* X509_STORE_CTX_get0_untrusted(X509_STORE_CTX *ctx); void X509_STORE_CTX_set0_untrusted(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); @@ -97,9 +94,6 @@ for example in a PKCS#7 structure. X509_STORE_CTX_get0_param() retrieves an internal pointer to the verification parameters associated with B. -X509_STORE_CTX_get0_cert() retrieves an internal pointer to the -certificate being verified by the B. - X509_STORE_CTX_get0_untrusted() retrieves an internal pointer to the stack of untrusted certifieds associated with B. diff --git a/doc/crypto/d2i_PKCS8PrivateKey.pod b/doc/crypto/d2i_PKCS8PrivateKey.pod index 9170fd5ca5..164d93ff4f 100644 --- a/doc/crypto/d2i_PKCS8PrivateKey.pod +++ b/doc/crypto/d2i_PKCS8PrivateKey.pod @@ -35,7 +35,7 @@ The PKCS#8 functions encode and decode private keys in PKCS#8 format using both PKCS#5 v1.5 and PKCS#5 v2.0 password based encryption algorithms. Other than the use of DER as opposed to PEM these functions are identical to the -corresponding B function as described in the L manual page. +corresponding B function as described in L. =head1 NOTES @@ -47,7 +47,7 @@ to memory BIOs, see L for details. =head1 SEE ALSO -L +L =head1 COPYRIGHT diff --git a/doc/ssl/SSL_get_version.pod b/doc/ssl/SSL_get_version.pod index 8e26d43921..23b6497d4f 100644 --- a/doc/ssl/SSL_get_version.pod +++ b/doc/ssl/SSL_get_version.pod @@ -21,7 +21,7 @@ SSL_is_dtls() returns one if the connection is using DTLS, zero if not. =head1 RETURN VALUES -SSL_get_verison() returns one of the following strings: +SSL_get_version() returns one of the following strings: =over 4 diff --git a/util/find-doc-nits.pl b/util/find-doc-nits.pl index cd30dfeb26..69d7c93521 100755 --- a/util/find-doc-nits.pl +++ b/util/find-doc-nits.pl @@ -38,10 +38,6 @@ sub name_synopsis() my $filename = shift; my $contents = shift; - # If it's a generic page (all lowercase), or apps, skip it. - return if $filename =~ /[a-z]+\.pod/; - return if $filename =~ m@/apps/@; - # Get NAME section and all words in it. return unless $contents =~ /=head1 NAME(.*)=head1 SYNOPSIS/ms; my $tmp = $1; @@ -71,12 +67,21 @@ sub name_synopsis() return unless $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms; my $syn = $1; foreach my $line ( split /\n+/, $syn ) { - next if $line =~ /typedef/; - next if $line =~ /STACK_OF/; - next unless $line =~ /([A-Za-z0-9_]+)\(/; - print "$id $1 missing from NAME section\n" - unless defined $names{$1}; - $names{$1} = 2; + my $sym; + $line =~ s/STACK_OF\([^)]+\)//; + if ( $line =~ /typedef.* (\S+);/ ) { + $sym = $1; + } elsif ( $line =~ /#define (\S+)/ ) { + $sym = $1; + } elsif ( $line =~ /([A-Za-z0-9_]+)\(/ ) { + $sym = $1; + } + else { + next; + } + print "$id $sym missing from NAME section\n" + unless defined $names{$sym}; + $names{$sym} = 2; } foreach my $n ( keys %names ) { @@ -101,7 +106,9 @@ sub check() my $id = "${filename}:1:"; &name_synopsis($id, $filename, $contents) - unless $contents =~ /=for comment generic/; + unless $contents =~ /=for comment generic/ + or $contents =~ /=for comment openssl_manual_section:7/ + or $filename =~ m@/apps/@; print "$id doesn't start with =pod\n" if $contents !~ /^=pod/; -- 2.34.1