Add docs

Signed-off-by: Klim Tsoutsman <klim@tsoutsman.com>

Cargo.lock

@@ -148,7 +148,6 @@ dependencies = [
  "cfg-if",
  "icrate",
  "jni",
- "log",
  "objc2",
  "robius-android-env",
 ]

Cargo.toml

@@ -3,9 +3,12 @@ name = "robius-open"
 version = "0.1.0"
 edition = "2021"
 
+[features]
+default = ["android-result"]
+android-result = []
+
 [dependencies]
 cfg-if = "1.0.0"
-log = "*"
 
 [target.'cfg(target_os = "android")'.dependencies.jni]
 version = "0.21.1"

src/lib.rs

@@ -6,6 +6,28 @@
 //!     .open()
 //!     .expect("failed to open telephone URI");
 //! ```
+//!
+//! Supports:
+//! - macOS (`NSWorkspace`)
+//! - Android (`android/content/Intent`)
+//! - Linux (`xdg-open`)
+//! - Windows (`start`)
+//! - WIP: iOS (`UIApplication`)
+//!
+//! # Android
+//! To use the library on Android, you must add the following to the app
+//! manifest: ```xml
+//! <uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"
+//!     tools:ignore="QueryAllPackagesPermission" />
+//!
+//! <queries>
+//!     <intent>
+//!         <action android:name="android.intent.action.MAIN" />
+//!     </intent>
+//! </queries>
+//! ```
+//! or alternatively, disable the `android-result` feature. However, disabling this feature will
+//! make [`Uri::open`] always return `Ok`, regardless of whether the URI was successfully opened.
 #![allow(clippy::result_unit_err)]
 
 mod sys;

src/sys/android.rs

@@ -48,33 +48,38 @@ impl<'a, 'b> Uri<'a, 'b> {
             )
             .unwrap();
 
-        let package_manager = env
-            .call_method(
-                current_activity,
-                "getPackageManager",
-                "()Landroid/content/pm/PackageManager;",
-                &[],
-            )
-            .unwrap()
-            .l()
-            .unwrap();
+        #[cfg(feature = "android-result")]
+        let is_err = {
+            let package_manager = env
+                .call_method(
+                    current_activity,
+                    "getPackageManager",
+                    "()Landroid/content/pm/PackageManager;",
+                    &[],
+                )
+                .unwrap()
+                .l()
+                .unwrap();
 
-        let component_name = env
-            .call_method(
-                &intent,
-                "resolveActivity",
-                "(Landroid/content/pm/PackageManager;)Landroid/content/ComponentName;",
-                &[JValueGen::Object(&package_manager)],
-            )
-            .unwrap()
-            .l()
-            .unwrap();
+            let component_name = env
+                .call_method(
+                    &intent,
+                    "resolveActivity",
+                    "(Landroid/content/pm/PackageManager;)Landroid/content/ComponentName;",
+                    &[JValueGen::Object(&package_manager)],
+                )
+                .unwrap()
+                .l()
+                .unwrap();
 
-        if component_name.as_raw().is_null() {
+            component_name.as_raw().is_null()
+        };
+        #[cfg(not(feature = "android_result"))]
+        let is_err = false;
+
+        if is_err {
             // NOTE: If the correct permissions aren't added to the app manifest,
             // resolveActivity will return null regardless.
-            //
-            // if false {
             Err(())
         } else {
             env.call_method(