documentation: Format.pp_print_newline wording (#12028)

Make it clearer that `Format.pp_print_newline` always flushes the new line it emits.

2 files changed, 7 insertions, 6 deletions

diff --git a/stdlib/format.ml b/stdlib/format.ml
index 669494be53..b7c53a7703 100644
--- a/stdlib/format.ml
+++ b/stdlib/format.ml
@@ -604,14 +604,14 @@ let clear_tag_stack state =
 
 
 (* Flushing pretty-printer queue. *)
-let pp_flush_queue state b =
+let pp_flush_queue state ~end_with_newline =
   clear_tag_stack state;
   while state.pp_curr_depth > 1 do
     pp_close_box state ()
   done;
   state.pp_right_total <- pp_infinity;
   advance_left state;
-  if b then pp_output_newline state;
+  if end_with_newline then pp_output_newline state;
   pp_rinit state
 
 (*
@@ -668,9 +668,9 @@ and pp_open_box state indent = pp_open_box_gen state indent Pp_box
    [pp_print_newline] behaves as [pp_print_flush] after printing an additional
    new line. *)
 let pp_print_newline state () =
-  pp_flush_queue state true; state.pp_out_flush ()
+  pp_flush_queue state ~end_with_newline:true; state.pp_out_flush ()
 and pp_print_flush state () =
-  pp_flush_queue state false; state.pp_out_flush ()
+  pp_flush_queue state ~end_with_newline:false; state.pp_out_flush ()
 
 
 (* To get a newline when one does not want to close the current box. *)
@@ -1077,7 +1077,7 @@ let get_stdbuf () = DLS.get stdbuf_key
    Formatter [ppf] is supposed to print to buffer [buf], otherwise this
    function is not really useful. *)
 let flush_buffer_formatter buf ppf =
-  pp_flush_queue ppf false;
+  pp_flush_queue ppf ~end_with_newline:false;
   let s = Buffer.contents buf in
   Buffer.reset buf;
   s
diff --git a/stdlib/format.mli b/stdlib/format.mli
index ef8093bb1b..b2544b8e6c 100644
--- a/stdlib/format.mli
+++ b/stdlib/format.mli
@@ -407,7 +407,8 @@ val print_newline : unit -> unit
 
   All open pretty-printing boxes are closed, all pending text is printed.
 
-  Equivalent to {!print_flush} followed by a new line.
+  Equivalent to {!print_flush} with a new line emitted on the pretty-printer
+  low-level output device immediately before the device is flushed.
   See corresponding words of caution for {!print_flush}.
 
   Note: this is not the normal way to output a new line;