Improve documentation of BitArchiveEditor::deleteItem

include/bit7z/bitarchiveeditor.hpp

@@ -137,30 +137,37 @@ class BIT7Z_MAYBE_UNUSED BitArchiveEditor final : public BitArchiveWriter {
         void updateItem( const tstring& itemPath, istream& inStream );
 
         /**
-         * @brief Marks the item at the given index as deleted.
+         * @brief Marks as deleted the item at the given index.
          *
          * @note By default, if the item is a folder, only its metadata is deleted, not the files within it.
          *       If instead the policy is set to DeletePolicy::RecurseDirs,
          *       then the items within the folder will also be deleted.
          *
          * @param index  the index of the item to be deleted.
          * @param policy the policy to be used when deleting items.
+         *
+         * @throws BitException if the index is invalid.
          */
         void deleteItem( uint32_t index, DeletePolicy policy = DeletePolicy::ItemOnly );
 
         /**
-         * @brief Marks the item(s) with the given path (in the archive) as deleted.
+         * @brief Marks as deleted the archive's item(s) with the specified path.
+         *
+         * @note By default, if the marked item is a folder, only its metadata will be deleted, not the files within it.
+         *       To delete the folder contents as well, set the `policy` to `DeletePolicy::RecurseDirs`.
          *
-         * @note By default, an item is marked as deleted if its path is lexicographically equivalent to the given path.
-         *       If a marked item is a folder, only its metadata will be deleted, not the files within it,
-         *       _unless_ the policy is set to DeletePolicy::RecurseDirs.
+         * @note The specified path must not begin with a path separator.
          *
-         * @note Generally, an archive may contain two or more items with the same paths;
-         *       if this is the case, all of them will be marked as deleted if they match the given path
-         *       (the same rules about the policy apply).
+         * @note A trailing path separator will _only_ be taken into account if the policy is DeletePolicy::RecurseDirs,
+         *       and will only match folder items; with DeletePolicy::ItemOnly, no item will match the path.
+         *
+         * @note Generally, archives may contain multiple items with the same paths.
+         *       If this is the case, all matching items will be marked as deleted according to the specified policy.
          *
          * @param itemPath the path (in the archive) of the item to be deleted.
          * @param policy   the policy to be used when deleting items.
+         *
+         * @throws BitException if the specified path is empty or invalid, or if no matching item could be found.
          */
         void deleteItem( const tstring& itemPath, DeletePolicy policy = DeletePolicy::ItemOnly );