Merge pull request #6 from MinnDevelopment/javadoc

1.2 Javadoc & Sources
Closes #7 Closes #1

Author: MinnDevelopment

.gitignore

@@ -2,3 +2,7 @@ src/test/*
 out/*
 build/*
 .idea/*
+.classpath
+.settings/*
+bin/*
+.project

README.md

@@ -1,23 +1,23 @@
 [ ![jitpack](https://jitpack.io/v/MinnDevelopment/Java-DiscordRPC.svg) ](https://jitpack.io/#MinnDevelopment/Java-DiscordRPC)
 # Java-DiscordRPC
 
-This library contains Java bindings for [Discord's official RPC SDK](https://github.com/discordapp/discord-rpc) using JNA. 
+This library contains Java bindings for [Discord's official RPC SDK](https://github.com/discordapp/discord-rpc) using JNA.
 
 This project provides binaries for `linux-x86-64`, `win32-x86-64` and `darwin`.
 
-If, on macOS, you get the following message:
-```
-Error in LSRegisterURL: -10811
-``` 
-it can safely be ignored.
+If, on macOS, you get the following message which can be ignored: `Error in LSRegisterURL: -10811`
+
+## Documentation
+
+You can see the official discord documentation in the [API Documentation](https://discordapp.com/developers/docs/rich-presence/how-to).
+<br>Alternatively you may visist the javadoc at [jitpack](https://jitpack.io/com/github/MinnDevelopment/Java-DiscordRPC/master-SNAPSHOT/javadoc/index.html).
 
 ## Examples
 
 ```java
 import club.minnced.discord.rpc.*;
 
 public class Main {
-
     public static void main(String[] args) {
         DiscordRPC lib = DiscordRPC.INSTANCE;
         String applicationId = "";
@@ -39,12 +39,15 @@ public class Main {
             }
         }, "RPC-Callback-Handler").start();
     }
-
 }
 ```
 
+> Note: To reveal this presence you have to start a window for your application.
+
 ## License
+
 Java-DiscordRPC is licensed under the Apache 2.0 License. The base DiscordRPC is licensed under the MIT license.
 
 ## Contributing
+
 Find something that is lacking? Fork the project and pull request!

build.gradle

@@ -15,14 +15,15 @@
  */
 plugins {
    id 'com.github.johnrengelman.shadow' version '2.0.1'
+   id 'maven-publish'
 }
 
 group 'club.minnced'
-version '1.0-SNAPSHOT'
+version '1.2'
 
 apply plugin: 'java'
 
-build.dependsOn shadowJar
+
 
 sourceCompatibility = 1.8
 targetCompatibility = 1.8
@@ -34,3 +35,72 @@ repositories {
 dependencies {
     compile 'net.java.dev.jna:jna:4.4.0'
 }
+
+wrapper {
+    gradleVersion = '4.2.1'
+}
+
+// Publishing
+
+task sources(type: Copy) {
+    from 'src/main/java'
+    into "$buildDir/sources"
+}
+
+classes.dependsOn sources
+
+jar {
+    baseName = project.name
+    manifest {
+        attributes 'Implementation-Version': version
+        attributes 'Target-Platforms': 'win32-x86-64, linux-x86-64, darwin'
+    }
+
+    dependsOn sources
+}
+
+javadoc {
+    failOnError = false
+    options.encoding = 'UTF-8'
+    options.addStringOption('-html5') // jdk-9 docs
+
+    dependsOn sources
+    source = sources.destinationDir
+}
+
+task sourcesJar(type: Jar, dependsOn: classes) {
+    classifier = 'sources'
+    from "$buildDir/sources"
+}
+
+task javadocJar(type: Jar, dependsOn: javadoc) {
+    classifier = 'javadoc'
+    from javadoc.destinationDir
+}
+
+publishing {
+    publications {
+        MavenProject(MavenPublication) {
+            from components.java
+            groupId group
+            artifactId archivesBaseName
+            version version
+
+            artifact javadocJar
+            artifact sourcesJar
+        }
+    }
+}
+
+build {
+    dependsOn clean
+    dependsOn jar
+    dependsOn javadocJar
+    dependsOn sourcesJar
+    dependsOn shadowJar
+
+    jar.mustRunAfter clean
+    javadocJar.mustRunAfter jar
+    sourcesJar.mustRunAfter javadocJar
+    shadowJar.mustRunAfter sourcesJar
+}

src/main/java/club/minnced/discord/rpc/DiscordEventHandlers.java

@@ -33,24 +33,39 @@
     void (*joinRequest)(const DiscordJoinRequest* request);
 } DiscordEventHandlers;
  */
-
+/**
+ * Struct containing handlers for RPC events
+ * <br>Provided handlers can be null.
+ */
 public class DiscordEventHandlers extends Structure
 {
+    /**
+     * Handler function for the ready event
+     */
     public interface OnReady extends Callback
     {
         void accept();
     }
 
+    /**
+     * Handler function for the exceptional events (error, disconnect)
+     */
     public interface OnStatus extends Callback
     {
         void accept(int errorCode, String message);
     }
 
+    /**
+     * Handler function for game update events (joinGame, spectateGame)
+     */
     public interface OnGameUpdate extends Callback
     {
         void accept(String secret);
     }
 
+    /**
+     * Handler function for user join requests
+     */
     public interface OnJoinRequest extends Callback
     {
         void accept(DiscordJoinRequest request);
@@ -65,11 +80,29 @@ public interface OnJoinRequest extends Callback
        "joinRequest"
     ));
 
+    /**
+     * Called when the RPC connection has been established
+     */
     public OnReady ready;
+    /**
+     * Called when the RPC connection has been severed
+     */
     public OnStatus disconnected;
+    /**
+     * Called when an internal error is caught within the SDK
+     */
     public OnStatus errored;
+    /**
+     * Called when the logged in user joined a game
+     */
     public OnGameUpdate joinGame;
+    /**
+     * Called when the logged in user joined to spectate a game
+     */
     public OnGameUpdate spectateGame;
+    /**
+     * Called when another discord user wants to join the game of the logged in user
+     */
     public OnJoinRequest joinRequest;
 
     @Override

src/main/java/club/minnced/discord/rpc/DiscordJoinRequest.java

@@ -29,7 +29,9 @@
     const char* avatar;
 } DiscordJoinRequest;
  */
-
+/**
+ * Struct binding for a discord join request.
+ */
 public class DiscordJoinRequest extends Structure
 {
     private static final List<String> FIELD_ORDER = Collections.unmodifiableList(Arrays.asList(
@@ -38,8 +40,17 @@ public class DiscordJoinRequest extends Structure
             "avatar"
     ));
 
+    /**
+     * The userId for the user that requests to join
+     */
     public String userId;
+    /**
+     * The username of the user that requests to join
+     */
     public String username;
+    /**
+     * The avatar of the user that requests to join
+     */
     public String avatar;
 
     @Override

src/main/java/club/minnced/discord/rpc/DiscordRPC.java

@@ -19,23 +19,134 @@
 import com.sun.jna.Library;
 import com.sun.jna.Native;
 
+/**
+ * Core library binding for the official <a href="https://github.com/discordapp/discord-rpc" target="_blank">Discord RPC SDK</a>.
+ * <br>Use {@link #INSTANCE} to access this library.
+ * 
+ * <h1>Supported Architectures</h1>
+ * <ul>
+ *   <li>Windows x86-64</li>
+ *   <li>Linux x86-64</li>
+ *   <li>Darwin</li>
+ * </ul>
+ */
 public interface DiscordRPC extends Library
 {
+    /**
+     * Library instance.
+     */
     DiscordRPC INSTANCE = Native.loadLibrary("discord-rpc", DiscordRPC.class);
 
+    /**
+     * Used to decline a request via {@link #Discord_Respond(String, int)}
+     * @see #DISCORD_REPLY_YES
+     */
     int DISCORD_REPLY_NO = 0;
+    /** 
+     * Used to accept a request via {@link #Discord_Respond(String, int)} 
+     * @see #DISCORD_REPLY_NO
+     */
     int DISCORD_REPLY_YES = 1;
+    /**
+     * Currently unsused response, treated like NO.
+     * Used with {@link #Discord_Respond(String, int)}
+     * @see #DISCORD_REPLY_NO
+     */
     int DISCORD_REPLY_IGNORE = 2;
 
+    /**
+     * Initializes the library, supply with application details and event handlers.
+     * Handlers are only called when the {@link #Discord_RunCallbacks()} method is invoked!
+     * <br><b>Before closing the application it is recommended to call {@link #Discord_Shutdown()}</b>
+     * 
+     * @param applicationId
+     *        The ID for this RPC application, 
+     *        retrieved from the <a href="https://discordappc.com/developers/applications/me" target="_blank">developer dashboard</a>
+     * @param handlers
+     *        Nullable instance of {@link club.minnced.discord.rpc.DiscordEventHandlers}
+     * @param autoRegister
+     *        {@code true} to automatically call {@link #Discord_RegisterSteamGame(String, String)} or {@link #Discord_Register(String, String)}
+     * @param steamId
+     *        Possible steam ID of the running game
+     */
     void Discord_Initialize(String applicationId,
                             DiscordEventHandlers handlers,
                             boolean autoRegister,
                             String steamId);
+    
+    /**
+     * Shuts the RPC connection down.
+     * If not currently connected, this does nothing.
+     */
     void Discord_Shutdown();
 
+    /**
+     * Executes the registered handlers for currently queued events.
+     * <br>If this is not called the handlers will not receive any events!
+     * 
+     * <p>It is recommended to call this in a <u>2 second interval</u>
+     */
     void Discord_RunCallbacks();
+
+    /**
+     * Polls events from the RPC pipe and pushes the currently queued presence.
+     * <br>This will be performed automatically if the attached binary
+     * has an enabled IO thread (default)
+     * 
+     * <p><b>If the IO-Thread has been enabled this will not be supported!</b>
+     */
     void Discord_UpdateConnection();
 
+    /**
+     * Updates the currently set presence of the logged in user.
+     * <br>Note that the client only updates its presence every <b>15 seconds</b>
+     * and queues all additional presence updates.
+     * 
+     * @param struct
+     *        The new presence to use, or null to reset
+     * 
+     * @see club.minnced.discord.rpc.DiscordRichPresence
+     */
     void Discord_UpdatePresence(DiscordRichPresence struct);
+
+    /**
+     * Responds to the given user with the specified reply type.
+     * 
+     * <h1>Possible Replies</h1>
+     * <ul>
+     *   <li>{@link #DISCORD_REPLY_NO}</li>
+     *   <li>{@link #DISCORD_REPLY_YES}</li>
+     *   <li>{@link #DISCORD_REPLY_IGNORE}</li>
+     * </ul>
+     * 
+     * @param userid
+     *        The id of the user to respond to
+     * @param reply
+     *        The reply type
+     * 
+     * @see   club.minnced.discord.rpc.DiscordJoinRequest#userId DiscordJoinRequest.userId
+     */
     void Discord_Respond(String userid, int reply);
+
+    /**
+     * Registers the given application so it can be run by the discord client. {@code discord-<appid>://}
+     * 
+     * @param applicationId
+     *        The ID of the application to register
+     * @param command
+     *        The command for the application startup, or {@code null} to use the
+     *        current executable's path
+     */
+    void Discord_Register(String applicationId, String command);
+
+    /**
+     * Similar to {@link #Discord_Register(String, String)} but uses the steam 
+     * game's installation path.
+     * 
+     * @param applicationId
+     *        The ID of the application to register
+     * @param steamId
+     *        The steam ID for the game
+     */
+    void Discord_RegisterSteamGame(String applicationId, String steamId);
 }