From: Eric Biggers <ebiggers3@gmail.com>
Date: Sun, 12 May 2013 00:57:38 +0000 (-0500)
Subject: wimlib.h: Document wimlib_add_empty_image()
X-Git-Tag: v1.4.0~106
X-Git-Url: https://wimlib.net/git/?p=wimlib;a=commitdiff_plain;h=603da5edd9d878b6ffeb11508a18356e5c324aaf

wimlib.h: Document wimlib_add_empty_image()
---

diff --git a/src/wimlib.h b/src/wimlib.h
index 72854e13..a50c0ede 100644
--- a/src/wimlib.h
+++ b/src/wimlib.h
@@ -1001,13 +1001,37 @@ enum wimlib_error_code {
 };
 
 
-/** Used to indicate that no WIM image or an invalid WIM image. */
+/** Used to indicate no WIM image or an invalid WIM image. */
 #define WIMLIB_NO_IMAGE		0
 
 /** Used to specify all images in the WIM. */
 #define WIMLIB_ALL_IMAGES	(-1)
 
-/** XXX */
+/**
+ * Appends an empty image to a WIM file.  This empty image will initially
+ * contain no files or directories, although if written without further
+ * modifications, a root directory will be created automatically for it.
+ *
+ * @param wim
+ *	Pointer to the ::WIMStruct for the WIM file to which the image is to be
+ *	added.
+ * @param name
+ *	Name to give the new image.
+ * @param new_idx_ret
+ *	If non-<code>NULL</code>, the index of the newly added image is returned
+ *	in this location.
+ *
+ * @return 0 on success; nonzero on failure.  The possible error codes are:
+ *
+ * @retval ::WIMLIB_ERR_INVALID_PARAM
+ *	@a name was @c NULL or an empty string.
+ * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
+ *	@a wim is part of a split WIM.
+ * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
+ *	There is already an image in @a wim named @a name.
+ * @retval ::WIMLIB_ERR_NOMEM
+ *	Failed to allocate the memory needed to add the new image.
+ */
 extern int
 wimlib_add_empty_image(WIMStruct *wim,
 		       const wimlib_tchar *name,