Provide a detailed description of the libarchive module map file

diff --git a/libarchive/module.modulemap b/libarchive/module.modulemap
index e570d01a4d3cc365a4d2991839ab093cce9c61a4..70f70fc3a1a2dfe5dc7f043c027c688d47291999 100644 (file)
--- a/libarchive/module.modulemap
+++ b/libarchive/module.modulemap
@@ -1,3 +1,33 @@
+/*
+ * Clang Module Map for libarchive
+ *
+ * What this is:
+ * This file tells the Clang compiler how to treat libarchive as a "module" -
+ * a self-contained unit of code that can be imported all at once instead of
+ * including individual header files. Think of it like a package definition.
+ *
+ * How it works:
+ * - When you write `@import CArchive` (Objective-C) or `import CArchive` (Swift),
+ *   the compiler uses this file to know which headers belong to libarchive
+ * - Instead of processing each #include separately, the compiler can load a
+ *   pre-compiled version of the entire library, making builds faster
+ * - This also provides better dependency tracking and can catch issues like
+ *   conflicting macro definitions between libraries
+ *
+ * When to update:
+ * Update this file whenever:
+ * - New public header files are added to libarchive's libarchive/ directory
+ * - Public headers are removed or renamed
+ * - The library's API structure changes significantly
+ *
+ * You typically don't need to update this for:
+ * - Internal implementation changes
+ * - Private/internal header modifications
+ * - Documentation updates
+ *
+ * NOTE: This only affects projects using Clang with modules enabled. Traditional
+ * #include-based builds will continue to work normally with or without this file.
+ */
 module CArchive {
   header "archive.h"
   header "archive_entry.h"