From 71aef9e0494819ed3d200439408e96963c7d4103 Mon Sep 17 00:00:00 2001 From: Florian Angeletti Date: Thu, 23 Feb 2023 17:28:44 +0100 Subject: documentation: Format.pp_print_newline wording (#12028) Make it clearer that `Format.pp_print_newline` always flushes the new line it emits. --- stdlib/format.ml | 10 +++++----- stdlib/format.mli | 3 ++- 2 files changed, 7 insertions(+), 6 deletions(-) (limited to 'stdlib') 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; -- cgit v1.2.1