BIO_new_bio_pair() was unnecessarily described in it's own page as well as in

BIO_s_bio.pod.  The most logical is to move everything needed from
BIO_new_bio_pair.pod to BIO_s_bio.pod (including the nice example)
and toss BIO_new_bio_pair.pod.  I hope I got all the info over properly.
PR: 370

doc/crypto/BIO_new_bio_pair.pod

-=pod
-
-=head1 NAME
-
-BIO_new_bio_pair - create a new BIO pair
-
-=head1 SYNOPSIS
-
- #include <openssl/bio.h>
-
- int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
-
-=head1 DESCRIPTION
-
-BIO_new_bio_pair() creates a buffering BIO pair based on the
-L<SSL_set_bio(3)|SSL_set_bio(3)> method. The BIO pair has two endpoints between which
-data can be buffered. Its typical use is to connect one endpoint as underlying
-input/output BIO to an SSL and access the other one controlled by the program
-instead of accessing the network connection directly.
-
-The two new BIOs B<bio1> and B<bio2> are symmetric with respect to their
-functionality. The size of their buffers is determined by B<writebuf1> and
-B<writebuf2>. If the size give is 0, the default size is used.
-
-BIO_new_bio_pair() does not check whether B<bio1> or B<bio2> do point to
-some other BIO, the values are overwritten, BIO_free() is not called.
-
-The two BIOs, even though forming a BIO pair and must be BIO_free()'ed
-separately. This can be of importance, as some SSL-functions like SSL_set_bio()
-or SSL_free() call BIO_free() implicitly, so that the peer-BIO is left
-untouched and must also be BIO_free()'ed.
-
-=head1 EXAMPLE
-
-The BIO pair can be used to have full control over the network access of an
-application. The application can call select() on the socket as required
-without having to go through the SSL-interface.
-
- BIO *internal_bio, *network_bio;
- ...
- BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
- SSL_set_bio(ssl, internal_bio, internal_bio);
- SSL_operations();
- ...
-
- application |   TLS-engine
-    |        |
-    +----------> SSL_operations()
-             |     /\    ||
-             |     ||    \/
-             |   BIO-pair (internal_bio)
-    +----------< BIO-pair (network_bio)
-    |        |
-  socket     |
-
-  ...
-  SSL_free(ssl);		/* implicitly frees internal_bio */
-  BIO_free(network_bio);
-  ...
-
-As the BIO pair will only buffer the data and never directly access the
-connection, it behaves non-blocking and will return as soon as the write
-buffer is full or the read buffer is drained. Then the application has to
-flush the write buffer and/or fill the read buffer.
-
-Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO
-and must be transfered to the network. Use BIO_ctrl_get_read_request() to
-find out, how many bytes must be written into the buffer before the
-SSL_operation() can successfully be continued.
-
-=head1 WARNING
-
-As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ
-condition, but there is still data in the write buffer. An application must
-not rely on the error value of SSL_operation() but must assure that the
-write buffer is always flushed first. Otherwise a deadlock may occur as
-the peer might be waiting for the data before being able to continue.
-
-=head1 RETURN VALUES
-
-The following return values can occur:
-
-=over 4
-
-=item 1
-
-The BIO pair was created successfully. The new BIOs are available in
-B<bio1> and B<bio2>.
-
-=item 0
-
-The operation failed. The NULL pointer is stored into the locations for
-B<bio1> and B<bio2>. Check the error stack for more information.
-
-=back
-
-=head1 SEE ALSO
-
-L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
-L<BIO_ctrl_pending(3)|BIO_ctrl_pending(3)>,
-L<BIO_ctrl_get_read_request(3)|BIO_ctrl_get_read_request(3)>
-
-=cut

doc/crypto/BIO_s_bio.pod

@@ -76,7 +76,9 @@ BIO_get_write_buf_size() returns the size of the write buffer.
 BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and
 BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2>
 with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is
-zero then the default size is used.
+zero then the default size is used.  BIO_new_bio_pair() does not check whether
+B<bio1> or B<bio2> do point to some other BIO, the values are overwritten,
+BIO_free() is not called.
 
 BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum
 length of data that can be currently written to the BIO. Writes larger than this
@@ -118,9 +120,59 @@ the application then waits for data to be available on the underlying transport
 before flushing the write buffer it will never succeed because the request was
 never sent!
 
+=head1 RETURN VALUES
+
+BIO_new_bio_pair() returns 1 on success, with the new BIOs available in
+B<bio1> and B<bio2>, or 0 on failure, with NULL pointers stored into the
+locations for B<bio1> and B<bio2>. Check the error stack for more information.
+
+[XXXXX: More return values need to be added here]
+
 =head1 EXAMPLE
 
-TBA
+The BIO pair can be used to have full control over the network access of an
+application. The application can call select() on the socket as required
+without having to go through the SSL-interface.
+
+ BIO *internal_bio, *network_bio;
+ ...
+ BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
+ SSL_set_bio(ssl, internal_bio, internal_bio);
+ SSL_operations();
+ ...
+
+ application |   TLS-engine
+    |        |
+    +----------> SSL_operations()
+             |     /\    ||
+             |     ||    \/
+             |   BIO-pair (internal_bio)
+    +----------< BIO-pair (network_bio)
+    |        |
+  socket     |
+
+  ...
+  SSL_free(ssl);		/* implicitly frees internal_bio */
+  BIO_free(network_bio);
+  ...
+
+As the BIO pair will only buffer the data and never directly access the
+connection, it behaves non-blocking and will return as soon as the write
+buffer is full or the read buffer is drained. Then the application has to
+flush the write buffer and/or fill the read buffer.
+
+Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO
+and must be transfered to the network. Use BIO_ctrl_get_read_request() to
+find out, how many bytes must be written into the buffer before the
+SSL_operation() can successfully be continued.
+
+=head1 WARNING
+
+As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ
+condition, but there is still data in the write buffer. An application must
+not rely on the error value of SSL_operation() but must assure that the
+write buffer is always flushed first. Otherwise a deadlock may occur as
+the peer might be waiting for the data before being able to continue.
 
 =head1 SEE ALSO