BIO_push.pod: fix confusing text and add details on corner cases

Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/17086)

doc/man3/BIO_push.pod

@@ -8,22 +8,27 @@ BIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a chain
 
  #include <openssl/bio.h>
 
- BIO *BIO_push(BIO *b, BIO *append);
+ BIO *BIO_push(BIO *b, BIO *next);
  BIO *BIO_pop(BIO *b);
  void BIO_set_next(BIO *b, BIO *next);
 
 =head1 DESCRIPTION
 
-The BIO_push() function appends the BIO B<append> to B<b>, it returns
+BIO_push() pushes I<b> on I<next>.
-B<b>.
+If I<b> is NULL the function does nothing and returns I<next>.
+Otherwise it prepends I<b>, which may be a single BIO or a chain of BIOs,
+to I<next> (unless I<next> is NULL).
+It then makes a control call on I<b> and returns I<b>.
 
-BIO_pop() removes the BIO B<b> from a chain and returns the next BIO
+BIO_pop() removes the BIO I<b> from any chain is is part of.
-in the chain, or NULL if there is no next BIO. The removed BIO then
+If I<b> is NULL the function does nothing and returns NULL.
-becomes a single BIO with no association with the original chain,
+Otherwise it makes a control call on I<b> and
-it can thus be freed or attached to a different chain.
+returns the next BIO in the chain, or NULL if there is no next BIO.
+The removed BIO becomes a single BIO with no association with
+the original chain, it can thus be freed or be made part of a different chain.
 
 BIO_set_next() replaces the existing next BIO in a chain with the BIO pointed to
-by B<next>. The new chain may include some of the same BIOs from the old chain
+by I<next>. The new chain may include some of the same BIOs from the old chain
 or it may be completely different.
 
 =head1 NOTES
@@ -33,41 +38,45 @@ joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain,
 the deleted BIO does not need to be at the end of a chain.
 
 The process of calling BIO_push() and BIO_pop() on a BIO may have additional
-consequences (a control call is made to the affected BIOs) any effects will
+consequences (a control call is made to the affected BIOs).
-be noted in the descriptions of individual BIOs.
+Any effects will be noted in the descriptions of individual BIOs.
 
 =head1 RETURN VALUES
 
-BIO_push() returns the end of the chain, B<b>.
+BIO_push() returns the head of the chain,
+which usually is I<b>, or I<next> if I<b> is NULL.
 
-BIO_pop() returns the next BIO in the chain, or NULL if there is no next
+BIO_pop() returns the next BIO in the chain,
-BIO.
+or NULL if there is no next BIO.
 
 =head1 EXAMPLES
 
-For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is
+For these examples suppose I<md1> and I<md2> are digest BIOs,
-a base64 BIO and B<f> is a file BIO.
+I<b64> is a base64 BIO and I<f> is a file BIO.
 
 If the call:
 
  BIO_push(b64, f);
 
-is made then the new chain will be B<b64-f>. After making the calls
+is made then the new chain will be I<b64-f>. After making the calls
 
  BIO_push(md2, b64);
  BIO_push(md1, md2);
 
-the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested
+the new chain is I<md1-md2-b64-f>. Data written to I<md1> will be digested
-by B<md1> and B<md2>, B<base64> encoded and written to B<f>.
+by I<md1> and I<md2>, base64 encoded, and finally written to I<f>.
 
 It should be noted that reading causes data to pass in the reverse
-direction, that is data is read from B<f>, B<base64> decoded and digested
+direction, that is data is read from I<f>, base64 decoded,
-by B<md2> and B<md1>. If the call:
+and digested by I<md2> and then I<md1>.
+
+The call:
 
  BIO_pop(md2);
 
-The call will return B<b64> and the new chain will be B<md1-b64-f> data can
+will return I<b64> and the new chain will be I<md1-b64-f>.
-be written to B<md1> as before.
+Data can be written to and read from I<md1> as before,
+except that I<md2> will no more be applied.
 
 =head1 SEE ALSO