feat: Improve docs a bit

Author: Berstanio

README.md

@@ -0,0 +1,28 @@
+## Overview
+
+This is a java interop library for [pymobiledevice3](https://github.com/doronz88/pymobiledevice3).  
+It uses an IPC protocol, to communicate with a python3 daemon running in the background.  
+All request/responses are implemented asyncronous.
+
+## How to use
+
+### The Daemon
+- Check if the Daemon is currently running with `DaemonHandler.isDaemonRunning()`.
+- If not, launch a new instance.
+  - Create a python env fist `PyInstallation installation = PyInstallationHandler.install(new File(</path/to/install/dir>));`
+    - You don't need to check for directory existence beforehand, the code is safe to use on every run.
+    - You should version the pathes using `PyMobileDevice3IPC.PROTOCOL_VERSION`, to avoid version collisions.  
+  - Then launch the daemon with `DaemonHandler.startDaemon(installation);`
+- Connect to the Daemon using `PyMobileDevice3IPC ipc = new PyMobileDevice3IPC()`. This object should be closed if not used anymore.
+
+
+### The IPC
+You can now use the `PyMobileDevice3IPC` created. All IPC methods return a `CompletableFuture` and are non-blocking.  
+The `DebugServer` methods require tunneld to be running. You can check the status with `PyMobileDevice3IPC#isTunneldRunning`.  
+You can launch tunneld with `PyMobileDevice3IPC#ensureTunneldRunning`, however this will ask for elevated priviliges on macos.
+
+## Debugging
+If you run into issues, you can: 
+- check the log file under `~/AppData/Local/Temp/javapymobiledevice3/` on windows and `/tmp/javapymobiledevice3` on UNIX.  
+- force shutdown a daemon using `PyMobileDevice3IPC#forceKillDaemon` and clear everything in the mentioned directories above.  
+- Launch a Daemon with `java.pymobiledevice3.debug` set. This will redirect the daemon stdout to your console.

src/main/java/io/github/berstanio/pymobiledevice3/daemon/DaemonHandler.java

@@ -23,7 +23,7 @@
 
 public class DaemonHandler {
     public static final String BASE_PORT_NAME = "javapymobiledevice3-" + PyMobileDevice3IPC.PROTOCOL_VERSION;
-    public static final File BASE_TEMP_DIR_WIN = Paths.get(System.getProperty("user.home"), "AppData", "Local", "Temp").toFile();
+    public static final File BASE_TEMP_DIR_WIN = Paths.get(System.getProperty("user.home"), "AppData", "Local", "Temp", "javapymobiledevice3").toFile();
     public static final File BASE_TEMP_DIR_UNIX = new File("/tmp/javapymobiledevice3/");
     public static final File UNIX_PORT_PATH = new File(BASE_TEMP_DIR_UNIX, BASE_PORT_NAME + "--" + getUnixUserId() + ".port");
     public static final File WINDOWS_PORT_PATH = new File(BASE_TEMP_DIR_WIN, BASE_PORT_NAME + ".port");

src/main/java/io/github/berstanio/pymobiledevice3/ipc/PyMobileDevice3IPC.java

@@ -154,7 +154,9 @@ private <U> CompletableFuture<U> createRequest(JSONObject request, BiConsumer<Co
         return future;
     }
 
-
+    /**
+     * @return A list of currently connected devices
+     */
     public CompletableFuture<DeviceInfo[]> listDevices() {
         JSONObject object = new JSONObject();
         object.put("command", "list_devices");
@@ -172,6 +174,9 @@ public CompletableFuture<DeviceInfo[]> listDevices() {
         });
     }
 
+    /**
+     * @return A list of UDID of currently connected devices. Does not involve pairing.
+     */
     public CompletableFuture<String[]> listDevicesUDID() {
         JSONObject object = new JSONObject();
         object.put("command", "list_devices_udid");
@@ -187,6 +192,9 @@ public CompletableFuture<String[]> listDevicesUDID() {
         });
     }
 
+    /**
+     * @return The first available device
+     */
     public CompletableFuture<DeviceInfo> getDevice()
     {
         return getDevice(null);
@@ -213,6 +221,8 @@ public CompletableFuture<DeviceInfo> getDevice(String uuid) {
     }
 
     /**
+     * Gets the bundle identifier for an app path
+     *
      * @param appPath The path to the app bundle, to retrieve the identifier from
      * @return The bundle identifier. Fails exceptionally, if no bundle identifier can be found
      */
@@ -251,6 +261,8 @@ public CompletableFuture<String> getInstalledPath(DeviceInfo info, String bundle
     }
 
     /**
+     * Installs an app onto the device
+     *
      * @param deviceInfo The device to install to.
      * @param path .app bundle path
      * @param installMode The installation mode. INSTALL/UPGRADE
@@ -279,6 +291,11 @@ public CompletableFuture<String> installApp(DeviceInfo deviceInfo, File path, In
         });
     }
 
+    /**
+     * Decodes a plist into an JSONObject
+     * @param path The path to a plist
+     * @return The decoded plist
+     */
     public CompletableFuture<JSONObject> decodePList(File path) {
         if (!path.exists() || path.isDirectory())
             throw new IllegalArgumentException("Path " + path.getAbsolutePath() + " does not point to file");
@@ -290,6 +307,11 @@ public CompletableFuture<JSONObject> decodePList(File path) {
         });
     }
 
+    /**
+     * Auto mount developer disk image for the device
+     *
+     * @param info The device to mount the developer disk image
+     */
     public CompletableFuture<Void> autoMountImage(DeviceInfo info) {
         JSONObject object = new JSONObject();
         object.put("command", "auto_mount_image");
@@ -299,6 +321,13 @@ public CompletableFuture<Void> autoMountImage(DeviceInfo info) {
         });
     }
 
+    /**
+     * Connect to the debugserver on the device. Needs tunneld running.
+     *
+     * @param info The device to connect to
+     * @param port The local port to open. 0 for arbitrary port
+     * @return The info about the connection
+     */
     public CompletableFuture<DebugServerConnection> debugServerConnect(DeviceInfo info, int port) {
         JSONObject object = new JSONObject();
         object.put("command", "debugserver_connect");
@@ -314,6 +343,11 @@ public CompletableFuture<DebugServerConnection> debugServerConnect(DeviceInfo in
         });
     }
 
+    /**
+     * Closes a debug server connection.
+     *
+     * @param connection The connection to close
+     */
     public CompletableFuture<Void> debugServerClose(DebugServerConnection connection) {
         JSONObject object = new JSONObject();
         object.put("command", "debugserver_close");
@@ -323,6 +357,14 @@ public CompletableFuture<Void> debugServerClose(DebugServerConnection connection
         });
     }
 
+    /**
+     * Opens a port forwarding to the target device.
+     *
+     * @param info The device to forward to
+     * @param remotePort The port to open on the device
+     * @param localPort The local port to forward. 0 for arbitrary port
+     * @return The information about the created forwarding
+     */
     public CompletableFuture<USBMuxForwarder> usbMuxForwarderCreate(DeviceInfo info, int remotePort, int localPort) {
         JSONObject object = new JSONObject();
         object.put("command", "usbmux_forwarder_open");
@@ -336,6 +378,11 @@ public CompletableFuture<USBMuxForwarder> usbMuxForwarderCreate(DeviceInfo info,
         });
     }
 
+    /**
+     * Closes a port forwarder.
+     *
+     * @param connection The connection to close
+     */
     public CompletableFuture<Void> usbMuxForwarderClose(USBMuxForwarder connection) {
         JSONObject object = new JSONObject();
         object.put("command", "usbmux_forwarder_close");
@@ -345,6 +392,9 @@ public CompletableFuture<Void> usbMuxForwarderClose(USBMuxForwarder connection)
         });
     }
 
+    /**
+     * Stops the daemon. Don't use this, it's for debugging purposes.
+     */
     public CompletableFuture<Void> forceKillDaemon() {
         JSONObject object = new JSONObject();
         object.put("id", commandId.getAndIncrement());
@@ -354,6 +404,11 @@ public CompletableFuture<Void> forceKillDaemon() {
         return CompletableFuture.completedFuture(null);
     }
 
+    /**
+     * Checks whether the tunneld service is running, needed for debugserver connection
+     *
+     * @return whether the tunneld service is running
+     */
     public CompletableFuture<Boolean> isTunneldRunning() {
         JSONObject object = new JSONObject();
         object.put("command", "is_tunneld_running");
@@ -362,6 +417,9 @@ public CompletableFuture<Boolean> isTunneldRunning() {
         });
     }
 
+    /**
+     * Launches the tunneld service. Will request elevated priviliges on macos.
+     */
     public CompletableFuture<Void> ensureTunneldRunning() {
         JSONObject object = new JSONObject();
         object.put("command", "ensure_tunneld_running");