-
-/* Given a directory entry with the name @name for the file with the inode
- * number @ino and device number @devno, create a new WIM dentry with an
- * associated inode, where the inode is shared if an inode with the same @ino
- * and @devno has already been created. On success, the new WIM dentry is
- * written to *dentry_ret, and its inode has i_nlink > 1 if a previously
- * existing inode was used.
+/*
+ * Allocate a new dentry, with hard link detection.
+ *
+ * @table
+ * The inode table being used for the current directory scan operation. It
+ * will contain the mapping from (ino, devno) pairs to inodes.
+ *
+ * @name
+ * The name to give the new dentry.
+ *
+ * @ino
+ * The inode number of the file, read from the filesystem.
+ *
+ * @devno
+ * The device number of the file, read from the filesystem. Proper setting
+ * of this parameter prevents cross-device hardlinks from being created.
+ * If this is not a problem (perhaps because the current directory scan
+ * operation is guaranteed to never traverse a filesystem boundary), then
+ * this parameter can just be a fixed value such as 0.
+ *
+ * @noshare
+ * If %true, the new dentry will not be hard linked to any existing inode,
+ * regardless of the values of @ino and @devno. If %false, normal hard
+ * link detection will be done.
+ *
+ * @dentry_ret
+ * On success, a pointer to the new dentry will be returned in this
+ * location. If i_nlink of the dentry's inode is greater than 1, then this
+ * function created a hard link to an existing inode rather than creating a
+ * new inode.
+ *
+ * On success, returns 0. On failure, returns WIMLIB_ERR_NOMEM or an error code
+ * resulting from a failed string conversion.