Fix some pod-page ordering nits
authorRich Salz <rsalz@akamai.com>
Thu, 15 Aug 2019 17:52:41 +0000 (13:52 -0400)
committerDr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Sun, 18 Aug 2019 22:03:33 +0000 (00:03 +0200)
The find-doc-nits script only looked for EXAMPLES, not EXAMPLE.
Fix the pattern and then fix the errors that resulted.

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/9602)

doc/man3/BIO_f_ssl.pod
doc/man3/BIO_s_mem.pod
doc/man3/BIO_set_callback.pod
doc/man3/SSL_CTX_get0_param.pod
util/find-doc-nits

index ba44133..82bb16c 100644 (file)
@@ -129,9 +129,25 @@ BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),
 BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(),
 BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros.
 
 BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(),
 BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros.
 
-=head1 EXAMPLE
+=head1 RETURN VALUES
+
+BIO_f_ssl() returns the SSL B<BIO_METHOD> structure.
+
+BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(),
+BIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on
+success or a value which is less than or equal to 0 if an error occurred.
+
+BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return
+a valid B<BIO> structure on success or B<NULL> if an error occurred.
+
+BIO_ssl_copy_session_id() returns 1 on success or 0 on error.
+
+BIO_do_handshake() returns 1 if the connection was established successfully.
+A zero or negative value is returned if the connection could not be established.
+
+=head1 EXAMPLES
 
 
-This SSL/TLS client example, attempts to retrieve a page from an
+This SSL/TLS client example attempts to retrieve a page from an
 SSL/TLS web server. The I/O routines are identical to those of the
 unencrypted example in L<BIO_s_connect(3)>.
 
 SSL/TLS web server. The I/O routines are identical to those of the
 unencrypted example in L<BIO_s_connect(3)>.
 
@@ -271,22 +287,6 @@ a client and also echoes the request to standard output.
  BIO_flush(sbio);
  BIO_free_all(sbio);
 
  BIO_flush(sbio);
  BIO_free_all(sbio);
 
-=head1 RETURN VALUES
-
-BIO_f_ssl() returns the SSL B<BIO_METHOD> structure.
-
-BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(),
-BIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on
-success or a value which is less than or equal to 0 if an error occurred.
-
-BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return
-a valid B<BIO> structure on success or B<NULL> if an error occurred.
-
-BIO_ssl_copy_session_id() returns 1 on success or 0 on error.
-
-BIO_do_handshake() returns 1 if the connection was established successfully.
-A zero or negative value is returned if the connection could not be established.
-
 =head1 HISTORY
 
 In OpenSSL before 1.0.0 the BIO_pop() call was handled incorrectly,
 =head1 HISTORY
 
 In OpenSSL before 1.0.0 the BIO_pop() call was handled incorrectly,
index 7cb9efa..b7c6fdf 100644 (file)
@@ -118,7 +118,16 @@ BIO_FLAGS_NONCLEAR_RST set has the same effect as a write operation.
 
 There should be an option to set the maximum size of a memory BIO.
 
 
 There should be an option to set the maximum size of a memory BIO.
 
-=head1 EXAMPLE
+=head1 RETURN VALUES
+
+BIO_s_mem() and BIO_s_secmem() return a valid memory B<BIO_METHOD> structure.
+
+BIO_set_mem_eof_return(), BIO_get_mem_data(), BIO_set_mem_buf() and BIO_get_mem_ptr()
+return 1 on success or a value which is less than or equal to 0 if an error occurred.
+
+BIO_new_mem_buf() returns a valid B<BIO> structure on success or NULL on error.
+
+=head1 EXAMPLES
 
 Create a memory BIO and write some data to it:
 
 
 Create a memory BIO and write some data to it:
 
@@ -139,14 +148,6 @@ Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
  BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
  BIO_free(mem);
 
  BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
  BIO_free(mem);
 
-=head1 RETURN VALUES
-
-BIO_s_mem() and BIO_s_secmem() return a valid memory B<BIO_METHOD> structure.
-
-BIO_set_mem_eof_return(), BIO_get_mem_data(), BIO_set_mem_buf() and BIO_get_mem_ptr()
-return 1 on success or a value which is less than or equal to 0 if an error occurred.
-
-BIO_new_mem_buf() returns a valid B<BIO> structure on success or NULL on error.
 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 
index a420267..afa482d 100644 (file)
@@ -211,11 +211,6 @@ the actual call parameter, see B<BIO_callback_ctrl>.
 
 =back
 
 
 =back
 
-=head1 EXAMPLE
-
-The BIO_debug_callback() function is a good example, its source is
-in crypto/bio/bio_cb.c
-
 =head1 RETURN VALUES
 
 BIO_get_callback_ex() and BIO_get_callback() return the callback function
 =head1 RETURN VALUES
 
 BIO_get_callback_ex() and BIO_get_callback() return the callback function
@@ -228,6 +223,11 @@ via a call to BIO_set_callback_arg().
 BIO_debug_callback() returns 1 or B<ret> if it's called after specific BIO
 operations.
 
 BIO_debug_callback() returns 1 or B<ret> if it's called after specific BIO
 operations.
 
+=head1 EXAMPLE
+
+The BIO_debug_callback() function is a good example, its source is
+in crypto/bio/bio_cb.c
+
 =head1 COPYRIGHT
 
 Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
 =head1 COPYRIGHT
 
 Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
index ff97064..795bbf0 100644 (file)
@@ -29,13 +29,6 @@ Typically parameters are retrieved from an B<SSL_CTX> or B<SSL> structure
 using SSL_CTX_get0_param() or SSL_get0_param() and an application modifies
 them to suit its needs: for example to add a hostname check.
 
 using SSL_CTX_get0_param() or SSL_get0_param() and an application modifies
 them to suit its needs: for example to add a hostname check.
 
-=head1 EXAMPLE
-
-Check hostname matches "www.foo.com" in peer certificate:
-
- X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl);
- X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0);
-
 =head1 RETURN VALUES
 
 SSL_CTX_get0_param() and SSL_get0_param() return a pointer to an
 =head1 RETURN VALUES
 
 SSL_CTX_get0_param() and SSL_get0_param() return a pointer to an
@@ -44,6 +37,13 @@ B<X509_VERIFY_PARAM> structure.
 SSL_CTX_set1_param() and SSL_set1_param() return 1 for success and 0
 for failure.
 
 SSL_CTX_set1_param() and SSL_set1_param() return 1 for success and 0
 for failure.
 
+=head1 EXAMPLE
+
+Check hostname matches "www.foo.com" in peer certificate:
+
+ X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl);
+ X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0);
+
 =head1 SEE ALSO
 
 L<X509_VERIFY_PARAM_set_flags(3)>
 =head1 SEE ALSO
 
 L<X509_VERIFY_PARAM_set_flags(3)>
index 499a68f..563a695 100755 (executable)
@@ -151,17 +151,17 @@ sub name_synopsis()
     }
 }
 
     }
 }
 
-# Check if SECTION is located before BEFORE
+# Check if SECTION ($3) is located before BEFORE ($4)
 sub check_section_location()
 {
 sub check_section_location()
 {
-    my $filename = shift;
+    my $id = shift;
     my $contents = shift;
     my $section = shift;
     my $before = shift;
 
     my $contents = shift;
     my $section = shift;
     my $before = shift;
 
-    return unless $contents =~ /=head1 $section/
-        and $contents =~ /=head1 $before/;
-    print "$filename: $section should be placed before $before section\n"
+    return
+        unless $contents =~ /=head1 $section/ and $contents =~ /=head1 $before/;
+    print "$id $section should be placed before $before section\n"
         if $contents =~ /=head1 $before.*=head1 $section/ms;
 }
 
         if $contents =~ /=head1 $before.*=head1 $section/ms;
 }
 
@@ -178,15 +178,15 @@ sub check()
         close POD;
     }
 
         close POD;
     }
 
-    # Check if EXAMPLES is located after RETURN VALUES section.
-    &check_section_location($filename, $contents, "RETURN VALUES", "EXAMPLES") if $filename =~ m|man3/|;
-    # Check if HISTORY is located after SEE ALSO
-    &check_section_location($filename, $contents, "SEE ALSO", "HISTORY") if $filename =~ m|man3/|;
-    # Check if SEE ALSO is located after EXAMPLES
-    &check_section_location($filename, $contents, "EXAMPLES", "SEE ALSO") if $filename =~ m|man3/|;
-
     my $id = "${filename}:1:";
 
     my $id = "${filename}:1:";
 
+    # Check ordering of some sections in man3
+    if ( $filename =~ m|man3/| ) {
+        &check_section_location($id, $contents, "RETURN VALUES", "EXAMPLE");
+        &check_section_location($id, $contents, "SEE ALSO", "HISTORY");
+        &check_section_location($id, $contents, "EXAMPLE", "SEE ALSO");
+    }
+
     &name_synopsis($id, $filename, $contents)
         unless $contents =~ /=for comment generic/
             or $filename =~ m@man[157]/@;
     &name_synopsis($id, $filename, $contents)
         unless $contents =~ /=for comment generic/
             or $filename =~ m@man[157]/@;