Improve Android-specific documentation

Author: sudoBash418

src/symbolize/gimli.rs

@@ -270,6 +270,19 @@ struct Cache {
 struct Library {
     name: OsString,
     #[cfg(target_os = "android")]
+    /// On Android, the dynamic linker [can map libraries directly from a
+    /// ZIP archive][ndk-linker-changes] (typically an `.apk`).
+    ///
+    /// The linker requires that these libraries are stored uncompressed
+    /// and page-aligned.
+    ///
+    /// These "embedded" libraries have filepaths of the form
+    /// `/path/to/my.apk!/lib/mylib.so` (where `/path/to/my.apk` is the archive
+    /// and `lib/mylib.so` is the name of the library within the archive).
+    ///
+    /// This mechanism is present on Android since API level 23.
+    ///
+    /// [ndk-linker-changes]: https://android.googlesource.com/platform/bionic/+/main/android-changes-for-ndk-developers.md#opening-shared-libraries-directly-from-an-apk
     zip_offset: Option<u64>,
     #[cfg(target_os = "aix")]
     /// On AIX, the library mmapped can be a member of a big-archive file.

src/symbolize/gimli/elf.rs

@@ -43,12 +43,18 @@ impl Mapping {
         })
     }
 
-    /// On Android, shared objects can be loaded directly from a
-    /// ZIP archive. For example, an app may load a library from
-    /// `/data/app/com.example/base.apk!/lib/x86_64/mylib.so`
+    /// On Android, shared objects can be loaded directly from a ZIP archive
+    /// (see: [`super::Library::zip_offset`]).
     ///
-    /// `zip_offset` should be page-aligned; the dynamic linker
-    /// requires this when it loads libraries.
+    /// If `zip_offset` is not None, we interpret the `path` as an
+    /// "embedded" library path, and the value of `zip_offset` tells us where
+    /// in the ZIP archive the library data starts.
+    ///
+    /// We expect `zip_offset` to be page-aligned because the dynamic linker
+    /// requires this. Otherwise, loading the embedded library will fail.
+    ///
+    /// If we fail to load an embedded library for any reason, we fallback to
+    /// interpreting the path as a literal file on disk (same as calling [`Self::new`]).
     #[cfg(target_os = "android")]
     pub fn new_android(path: &Path, zip_offset: Option<u64>) -> Option<Mapping> {
         fn map_embedded_library(path: &Path, zip_offset: u64) -> Option<Mapping> {
@@ -75,6 +81,7 @@ impl Mapping {
         }
 
         // if ZIP offset is given, try mapping as a ZIP-embedded library
+        // otherwise, fallback to mapping as a literal filepath
         if let Some(zip_offset) = zip_offset {
             map_embedded_library(path, zip_offset).or_else(|| Self::new(path))
         } else {