vim-patch:9.0.0379: cleaning up after writefile() is a hassle

Problem:    Cleaning up after writefile() is a hassle.
Solution:   Add the 'D' flag to defer deleting the written file.  Very useful
            in tests.

https://github.com/vim/vim/commit/806a273f3c84ecd475913d901890bb1929be9a0a

Co-authored-by: Bram Moolenaar <Bram@vim.org>

1 files changed, 26 insertions, 14 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index cb05718ab9..adb3164429 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -9507,31 +9507,43 @@ writefile({object}, {fname} [, {flags}])
 		When {object} is a |List| write it to file {fname}.  Each list
 		item is separated with a NL.  Each list item must be a String
 		or Number.
-		When {flags} contains "b" then binary mode is used: There will
-		not be a NL after the last list item.  An empty item at the
-		end does cause the last line in the file to end in a NL.
+		All NL characters are replaced with a NUL character.
+		Inserting CR characters needs to be done before passing {list}
+		to writefile().
 
 		When {object} is a |Blob| write the bytes to file {fname}
-		unmodified.
+		unmodified, also when binary mode is not specified.
 
-		When {flags} contains "a" then append mode is used, lines are
-		appended to the file: >
+		{flags} must be a String.  These characters are recognized:
+
+		'b'  Binary mode is used: There will not be a NL after the
+		     last list item.  An empty item at the end does cause the
+		     last line in the file to end in a NL.
+
+		'a'  Append mode is used, lines are appended to the file: >
 			:call writefile(["foo"], "event.log", "a")
 			:call writefile(["bar"], "event.log", "a")
 <
-		When {flags} contains "S" fsync() call is not used, with "s"
-		it is used, 'fsync' option applies by default. No fsync()
-		means that writefile() will finish faster, but writes may be
-		left in OS buffers and not yet written to disk. Such changes
-		will disappear if system crashes before OS does writing.
+		'D'  Delete the file when the current function ends.  This
+		     works like: >
+			:defer delete({fname})
+<		     Fails when not in a function.  Also see |:defer|.
+
+		's'  fsync() is called after writing the file.  This flushes
+		     the file to disk, if possible.  This takes more time but
+		     avoids losing the file if the system crashes.
+
+		'S'  fsync() is not called, even when 'fsync' is set.
+
+		     When {flags} does not contain "S" or "s" then fsync() is
+		     called if the 'fsync' option is set.
 
-		All NL characters are replaced with a NUL character.
-		Inserting CR characters needs to be done before passing {list}
-		to writefile().
 		An existing file is overwritten, if possible.
+
 		When the write fails -1 is returned, otherwise 0.  There is an
 		error message if the file can't be created or when writing
 		fails.
+
 		Also see |readfile()|.
 		To copy a file byte for byte: >
 			:let fl = readfile("foo", "b")