- * The new WIM is written to a temporary file and then renamed to the original
- * file after it is has been completely written. The temporary file currently
- * is made in the same directory as the original WIM file.
- *
- * After this function returns, @a wim must be freed using wimlib_free(). Any
- * further actions on @a wim before doing this are undefined.
+ * There are two ways that a WIM may be overwritten. The first is to do a full
+ * rebuild: the new WIM is written to a temporary file and then renamed to the
+ * original file after it is has been completely written. The temporary file
+ * currently is made in the same directory as the original WIM file. A full
+ * rebuild may take a while, but can be used even if images have been modified
+ * or deleted, will produce a WIM with no holes, and has little chance of
+ * unintentional data loss because the temporary WIM is fsync()ed before being
+ * renamed to the original WIM.
+ *
+ * The second way to overwrite a WIM is by appending to the end of it. This can
+ * be much faster than a full rebuild, but it only works if the only operations
+ * on the WIM have been to change the header or XML data, or to add new images.
+ * Writing a WIM in this mode begins with writing any new file resources *after*
+ * everything in the old WIM, even though this will leave a hole where the old
+ * lookup table, XML data, and integrity were. This is done so that the WIM
+ * remains valid even if the operation is aborted mid-write.
+ *
+ * By default, the overwrite mode is chosen based on the past operations
+ * performed on the WIM. Use the flag ::WIMLIB_WRITE_FLAG_REBUILD to explicitly
+ * request a full rebuild.
+ *
+ * In the temporary-file overwrite mode, no changes are made to the WIM on
+ * failure, and the temporary file is deleted (if possible). Abnormal
+ * termination of the program will result in the temporary file being orphaned.
+ * In the direct append mode, the WIM is truncated to the original length on
+ * failure, while abnormal termination of the program will result in extra data
+ * appended to the original WIM, but it will still be a valid WIM.