* dir.
* @retval ::WIMLIB_ERR_READ
* Failed to read a file in the directory tree rooted at @a dir.
+ * @retval ::WIMLIB_ERR_SPECIAL_FILE
+ * The directory tree rooted at @dir contains a special file that is not a
+ * directory, regular file, or symbolic link.
* @retval ::WIMLIB_ERR_STAT
* Failed obtain the metadata for a file or directory in the directory tree
* rooted at @a dir.
/**
* Deletes an image, or all images, from a WIM file.
*
- * All file resources referenced by the image(s) being deleted are removed from
- * the WIM if they are not referenced by any other images in the WIM.
+ * All streams referenced by the image(s) being deleted are removed from the
+ * lookup table of the WIM if they are not referenced by any other images in the
+ * WIM.
*
* @param wim
* Pointer to the ::WIMStruct for the WIM file that contains the image(s)
* @param image
* The number of the image to delete, or ::WIM_ALL_IMAGES to delete all
* images.
- * @return 0 on success; nonzero on error. On error, @a wim is left in an
- * indeterminate state and should be freed with wimlib_free().
+ * @return 0 on success; nonzero on failure. On failure, @a wim is guaranteed
+ * to be left unmodified only if @a image specified a single image. If instead
+ * @a image was ::WIM_ALL_IMAGES and @a wim contained more than one image, it's
+ * possible for some but not all of the images to have been deleted when a
+ * failure status is returned.
+ *
* @retval ::WIMLIB_ERR_DECOMPRESSION
* Could not decompress the metadata resource for @a image.
* @retval ::WIMLIB_ERR_INVALID_DENTRY
* The metadata resource for @a image in the WIM is invalid.
* @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA
* The security data for @a image in the WIM is invalid.
- * @retval ::WIMLIB_ERR_NOMEM Failed to allocate needed memory.
+ * @retval ::WIMLIB_ERR_NOMEM
+ * Failed to allocate needed memory.
* @retval ::WIMLIB_ERR_READ
* Could not read the metadata resource for @a image from the WIM.
* @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED