cleanup, docs

site/doc/pages/file_append.txt

@@ -2,16 +2,19 @@
 void file_append(String file_name, ...val)
 
 :params
-file_name : file name of file that should be written to
-...val : one or more values that should be written into the file
+file_name : file to append to, created if missing
+...val : one or more values appended in order
+return value : none
+
+:content
+Appends one or more values to a file, creating it if needed. Each call takes an exclusive lock for the append, so concurrent appends are serialized and readers wait for them; you never manage locks yourself.
+
+:example
+file_unlink("/tmp/doc-append.txt");
+file_append("/tmp/doc-append.txt", "a", "b", "c");
+print(file_get_contents("/tmp/doc-append.txt"), "\n");
 
 :see
 >sys
-
-:content
-Opens or creates a file and appends data to it.
-
-The append transparently takes an exclusive file lock for the duration of the append operation. Concurrent writers are serialized, and `file_get_contents()` waits for in-progress writes to finish; callers do not manage locks manually.
-
-:example
-print("file_append example\n");
+file_put_contents
+file_get_contents