Remove duplicated methods, consummate docs

api/src/main/java/io/github/libxposed/api/XposedContext.java

@@ -3,7 +3,9 @@ package io.github.libxposed.api;
 import android.content.Context;
 
 /**
- * The type Xposed context.
+ * Independent {@link Context} for each Xposed module loaded into the target process.<br/>
+ * This class should be extended by the Xposed framework as the implementation of Xposed interfaces.<br/>
+ * Modules should not use this class directly.
  */
 public abstract class XposedContext extends Context implements XposedInterface {
 

api/src/main/java/io/github/libxposed/api/XposedContextWrapper.java

@@ -14,170 +14,233 @@ import java.nio.ByteBuffer;
 import io.github.libxposed.api.utils.DexParser;
 
 /**
- * The type Xposed context wrapper.
+ * Wrap of {@link XposedContext} used by the modules for the purpose of shielding framework implementation details.
  */
-@SuppressWarnings("unused")
+@SuppressWarnings({"deprecation", "unused"})
 public class XposedContextWrapper extends ContextWrapper implements XposedInterface {
 
-    /**
-     * Instantiates a new Xposed context wrapper.
-     *
-     * @param base the base
-     */
     XposedContextWrapper(@NonNull XposedContext base) {
         super(base);
     }
 
-    /**
+    XposedContextWrapper(@NonNull XposedContextWrapper base) {
-     * Instantiates a new Xposed context wrapper.
-     *
-     * @param base the base
-     */
-    public XposedContextWrapper(@NonNull XposedContextWrapper base) {
         super(base);
     }
 
     /**
-     * Gets api version.
+     * Get the Xposed API version of current implementation.
      *
-     * @return the api version
+     * @return API version
      */
     final public int getAPIVersion() {
         return API;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @NonNull
     @Override
     final public XposedContext getBaseContext() {
         return (XposedContext) super.getBaseContext();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @NonNull
     @Override
     final public String getFrameworkName() {
         return getBaseContext().getFrameworkName();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @NonNull
     @Override
     final public String getFrameworkVersion() {
         return getBaseContext().getFrameworkVersion();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     final public long getFrameworkVersionCode() {
         return getBaseContext().getFrameworkVersionCode();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     final public int getFrameworkPrivilege() {
         return getBaseContext().getFrameworkPrivilege();
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Deprecated
     @Nullable
     @Override
     final public Object featuredMethod(String name, Object... args) {
         return getBaseContext().featuredMethod(name, args);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @NonNull
     @Override
     final public MethodUnhooker<BeforeHooker<Method>, Method> hookBefore(@NonNull Method origin, @NonNull BeforeHooker<Method> hooker) {
         return getBaseContext().hookBefore(origin, hooker);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @NonNull
     @Override
     final public MethodUnhooker<AfterHooker<Method>, Method> hookAfter(@NonNull Method origin, @NonNull AfterHooker<Method> hooker) {
         return getBaseContext().hookAfter(origin, hooker);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @NonNull
     @Override
     final public MethodUnhooker<Hooker<Method>, Method> hook(@NonNull Method origin, @NonNull Hooker<Method> hooker) {
         return getBaseContext().hook(origin, hooker);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @NonNull
     @Override
     final public MethodUnhooker<BeforeHooker<Method>, Method> hookBefore(@NonNull Method origin, int priority, @NonNull BeforeHooker<Method> hooker) {
         return getBaseContext().hookBefore(origin, priority, hooker);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @NonNull
     @Override
     final public MethodUnhooker<AfterHooker<Method>, Method> hookAfter(@NonNull Method origin, int priority, @NonNull AfterHooker<Method> hooker) {
         return getBaseContext().hookAfter(origin, priority, hooker);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @NonNull
     @Override
     final public MethodUnhooker<Hooker<Method>, Method> hook(@NonNull Method origin, int priority, @NonNull Hooker<Method> hooker) {
         return getBaseContext().hook(origin, priority, hooker);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @NonNull
     @Override
     final public <T> MethodUnhooker<BeforeHooker<Constructor<T>>, Constructor<T>> hookBefore(@NonNull Constructor<T> origin, @NonNull BeforeHooker<Constructor<T>> hooker) {
         return getBaseContext().hookBefore(origin, hooker);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @NonNull
     @Override
     final public <T> MethodUnhooker<AfterHooker<Constructor<T>>, Constructor<T>> hookAfter(@NonNull Constructor<T> origin, @NonNull AfterHooker<Constructor<T>> hooker) {
         return getBaseContext().hookAfter(origin, hooker);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @NonNull
     @Override
     final public <T> MethodUnhooker<Hooker<Constructor<T>>, Constructor<T>> hook(@NonNull Constructor<T> origin, @NonNull Hooker<Constructor<T>> hooker) {
         return getBaseContext().hook(origin, hooker);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @NonNull
     @Override
     final public <T> MethodUnhooker<BeforeHooker<Constructor<T>>, Constructor<T>> hookBefore(@NonNull Constructor<T> origin, int priority, @NonNull BeforeHooker<Constructor<T>> hooker) {
         return getBaseContext().hookBefore(origin, priority, hooker);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @NonNull
     @Override
     final public <T> MethodUnhooker<AfterHooker<Constructor<T>>, Constructor<T>> hookAfter(@NonNull Constructor<T> origin, int priority, @NonNull AfterHooker<Constructor<T>> hooker) {
         return getBaseContext().hookAfter(origin, priority, hooker);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @NonNull
     @Override
     final public <T> MethodUnhooker<Hooker<Constructor<T>>, Constructor<T>> hook(@NonNull Constructor<T> origin, int priority, @NonNull Hooker<Constructor<T>> hooker) {
         return getBaseContext().hook(origin, priority, hooker);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     final public boolean deoptimize(@NonNull Method method) {
         return getBaseContext().deoptimize(method);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     final public <T> boolean deoptimize(@NonNull Constructor<T> constructor) {
         return getBaseContext().deoptimize(constructor);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     final public void log(@NonNull String message) {
         getBaseContext().log(message);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     final public void log(@NonNull String message, @NonNull Throwable throwable) {
         getBaseContext().log(message, throwable);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Nullable
     @Override
     final public DexParser parseDex(@NonNull ByteBuffer dexData, boolean includeAnnotations) throws IOException {
         return getBaseContext().parseDex(dexData, includeAnnotations);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     final protected void attachBaseContext(Context base) {
         if (base instanceof XposedContext || base instanceof XposedContextWrapper) {

api/src/main/java/io/github/libxposed/api/XposedInterface.java

@@ -20,29 +20,30 @@ import io.github.libxposed.api.errors.HookFailedError;
 import io.github.libxposed.api.utils.DexParser;
 
 /**
- * The interface Xposed interface.
+ * Xposed interface for modules to operate on application processes.
  */
 @SuppressWarnings("unused")
 public interface XposedInterface {
     /**
-     * The constant API.
+     * SDK API version.
      */
     int API = 100;
 
     /**
-     * The constant FRAMEWORK_PRIVILEGE_ROOT.
+     * Indicates that the framework is running as root.
      */
     int FRAMEWORK_PRIVILEGE_ROOT = 0;
     /**
-     * The constant FRAMEWORK_PRIVILEGE_CONTAINER.
+     * Indicates that the framework is running in a container with a fake system_server.
      */
     int FRAMEWORK_PRIVILEGE_CONTAINER = 1;
     /**
-     * The constant FRAMEWORK_PRIVILEGE_APP.
+     * Indicates that the framework is running as a different app, which may have at most shell permission.
      */
     int FRAMEWORK_PRIVILEGE_APP = 2;
     /**
-     * The constant FRAMEWORK_PRIVILEGE_EMBEDDED.
+     * Indicates that the framework is embedded in the hooked app,
+     * which means {@link #getSharedPreferences} will be null and remote file is unsupported.
      */
     int FRAMEWORK_PRIVILEGE_EMBEDDED = 3;
 
@@ -321,42 +322,46 @@ public interface XposedInterface {
     }
 
     /**
-     * Gets framework name.
+     * Get the Xposed framework name of current implementation.
      *
-     * @return the framework name
+     * @return Framework name
      */
     @NonNull
     String getFrameworkName();
 
     /**
-     * Gets framework version.
+     * Get the Xposed framework version of current implementation.
      *
-     * @return the framework version
+     * @return Framework version
      */
     @NonNull
     String getFrameworkVersion();
 
     /**
-     * Gets framework version code.
+     * Get the Xposed framework version code of current implementation.
      *
-     * @return the framework version code
+     * @return Framework version code
      */
     long getFrameworkVersionCode();
 
     /**
-     * Gets framework privilege.
+     * Get the Xposed framework privilege of current implementation.
      *
-     * @return the framework privilege
+     * @return Framework privilege
      */
     int getFrameworkPrivilege();
 
     /**
-     * Featured method object.
+     * Additional methods provided by specific Xposed framework.
      *
-     * @param name the name
+     * @param name Featured method name
-     * @param args the args
+     * @param args Featured method arguments
-     * @return the object
+     * @return Featured method result
+     * @throws UnsupportedOperationException If the framework does not provide a method with given name
+     * @deprecated Normally, modules should never rely on implementation details about the Xposed framework,
+     * but if really necessary, this method can be used to acquire such information
      */
+    @Deprecated
     @Nullable
     Object featuredMethod(String name, Object... args);
 
@@ -560,7 +565,7 @@ public interface XposedInterface {
     DexParser parseDex(@NonNull ByteBuffer dexData, boolean includeAnnotations) throws IOException;
 
 
-    // Methods the same with context
+    // Methods the same with Context
 
     /**
      * Gets shared preferences.

api/src/main/java/io/github/libxposed/api/XposedModule.java

@@ -3,25 +3,33 @@ package io.github.libxposed.api;
 import androidx.annotation.NonNull;
 
 /**
- * The type Xposed module.
+ * Super class which all Xposed module entry classes should extend.<br/>
+ * Entry classes will be instantiated exactly once for each process.
  */
 @SuppressWarnings("unused")
 public abstract class XposedModule extends XposedContextWrapper implements XposedModuleInterface {
     /**
-     * Instantiates a new Xposed module.
+     * Instantiates a new Xposed module.<br/>
+     * When the module is loaded into the target process, the constructor will be called.
      *
-     * @param base  the base
+     * @param base  The base context provided by the framework, should not be used by the module
-     * @param param the param
+     * @param param Information about the process in which the module is loaded
      */
     public XposedModule(@NonNull XposedContext base, @NonNull ModuleLoadedParam param) {
         super(base);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public void onPackageLoaded(@NonNull PackageLoadedParam param) {
 
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public void onSystemServerLoaded(@NonNull SystemServerLoadedParam param) {
 

api/src/main/java/io/github/libxposed/api/XposedModuleInterface.java

@@ -1,128 +1,95 @@
 package io.github.libxposed.api;
 
 import android.content.pm.ApplicationInfo;
-import android.os.Bundle;
 
 import androidx.annotation.NonNull;
-import androidx.annotation.Nullable;
 
 /**
- * The interface Xposed module interface.
+ * Interface for module initialization.
  */
 @SuppressWarnings("unused")
 public interface XposedModuleInterface {
     /**
-     * The interface Module loaded param.
+     * Wraps information about the process in which the module is loaded.
      */
     interface ModuleLoadedParam {
         /**
-         * Is system server boolean.
+         * Get information about whether the module is running in system server.
          *
-         * @return the boolean
+         * @return {@code true} if the module is running in system server
          */
         boolean isSystemServer();
 
         /**
-         * Gets process name.
+         * Get the process name.
          *
-         * @return the process name
+         * @return The process name
          */
         @NonNull
         String getProcessName();
-
-        /**
-         * Gets app data dir.
-         *
-         * @return the app data dir
-         */
-        @NonNull
-        String getAppDataDir();
-
-        /**
-         * Gets extras.
-         *
-         * @return the extras
-         */
-        @Nullable
-        Bundle getExtras();
     }
 
     /**
-     * The interface System server loaded param.
+     * Wraps information about system server.
      */
     interface SystemServerLoadedParam {
         /**
-         * Gets class loader.
+         * Get the class loader of system server.
          *
-         * @return the class loader
+         * @return The class loader
          */
         @NonNull
         ClassLoader getClassLoader();
-
-        /**
-         * Gets extras.
-         *
-         * @return the extras
-         */
-        @Nullable
-        Bundle getExtras();
     }
 
     /**
-     * The interface Package loaded param.
+     * Wraps information about the package being loaded.
      */
     interface PackageLoadedParam {
         /**
-         * Gets package name.
+         * Get the package name of the package being loaded.
          *
-         * @return the package name
+         * @return The package name.
          */
         @NonNull
         String getPackageName();
 
         /**
-         * Gets app info.
+         * Get the ApplicationInfo of the package being loaded.
          *
-         * @return the app info
+         * @return The ApplicationInfo.
          */
         @NonNull
         ApplicationInfo getAppInfo();
 
         /**
-         * Gets class loader.
+         * Get the class loader of the package being loaded.
          *
-         * @return the class loader
+         * @return The class loader.
          */
         @NonNull
         ClassLoader getClassLoader();
 
         /**
-         * Is first application boolean.
+         * Get information about whether is this package the first and main package of the app process.
          *
-         * @return the boolean
+         * @return {@code true} if this is the first package.
          */
-        boolean isFirstApplication();
+        boolean isFirstPackage();
-
-        /**
-         * Gets extras.
-         *
-         * @return the extras
-         */
-        @Nullable
-        Bundle getExtras();
     }
 
     /**
-     * On package loaded.
+     * Get notified when a package is loaded into the app process.<br/>
+     * This callback could be invoked multiple times for the same process on each package.
      *
-     * @param param the param
+     * @param param Information about the package being loaded
      */
     void onPackageLoaded(@NonNull PackageLoadedParam param);
 
     /**
-     * On system server loaded.
+     * Get notified when the system server is loaded.
      *
-     * @param param the param
+     * @param param Information about system server
      */
     void onSystemServerLoaded(@NonNull SystemServerLoadedParam param);
 }