ndk-glue: Replace deprecated annotation on native_activity() with…

… doc-comments

It has been quite some time since we introduced this, and our
alternative implementation for more safely passing a native activity to
the user while interoperating cleanly with `ndk_context` still hasn't
found its way.

There are legitimate uses for `native_activity()` that cannot be
performed through the suggested `ndk_context::android_context().vm()`,
making the load of this deprecation warning heavier than the problem it
tries to prevent.

In order to keep some form of documentation for this issue going, it is
now explained in a doc-comment that is also partially replicated on the
other `static` getter functions.

ndk-glue/src/lib.rs

@@ -53,19 +53,30 @@ static LOOPER: Lazy<Mutex<Option<ForeignLooper>>> = Lazy::new(Default::default);
 
 static mut NATIVE_ACTIVITY: Option<NativeActivity> = None;
 
-#[deprecated = "Use `ndk_context::android_context().vm()` instead."]
+/// This function accesses a `static` variable internally and must only be used if you are sure
+/// there is exactly one version of `ndk_glue` in your dependency tree.
+///
+/// If you need access to the `JavaVM` through [`NativeActivity::vm()`] or Activity `Context`
+/// through [`NativeActivity::activity()`], please use the [`ndk_context`] crate and its
+/// [`ndk_context::android_context()`] getter to acquire the `JavaVM` and `Context` instead.
 pub fn native_activity() -> &'static NativeActivity {
     unsafe { NATIVE_ACTIVITY.as_ref().unwrap() }
 }
 
+/// This function accesses a `static` variable internally and must only be used if you are sure
+/// there is exactly one version of `ndk_glue` in your dependency tree.
 pub fn native_window() -> RwLockReadGuard<'static, Option<NativeWindow>> {
     NATIVE_WINDOW.read().unwrap()
 }
 
+/// This function accesses a `static` variable internally and must only be used if you are sure
+/// there is exactly one version of `ndk_glue` in your dependency tree.
 pub fn input_queue() -> RwLockReadGuard<'static, Option<InputQueue>> {
     INPUT_QUEUE.read().unwrap()
 }
 
+/// This function accesses a `static` variable internally and must only be used if you are sure
+/// there is exactly one version of `ndk_glue` in your dependency tree.
 pub fn content_rect() -> Rect {
     CONTENT_RECT.read().unwrap().clone()
 }

ndk/src/native_activity.rs

@@ -154,15 +154,17 @@ impl NativeActivity {
     /// });
     /// ```
     pub fn vm(&self) -> *mut jni_sys::JavaVM {
-        unsafe { self.ptr.as_ref().vm }
+        unsafe { self.ptr.as_ref() }.vm
     }
 
-    /// The `android.app.NativeActivity` instance
+    /// The [`android.app.NativeActivity`] instance
     ///
     /// In the JNI, this is named `clazz`; however, as the docs say, "it should really be named
     /// 'activity' instead of 'clazz', since it's a reference to the NativeActivity instance".
+    ///
+    /// [`android.app.NativeActivity`]: https://developer.android.com/reference/android/app/NativeActivity
     pub fn activity(&self) -> jni_sys::jobject {
-        unsafe { self.ptr.as_ref().clazz }
+        unsafe { self.ptr.as_ref() }.clazz
     }
 
     /// Path to the directory with the application's OBB files.