Refactor GHAppCreateTokenBuilder;

Add docs;

Signed-off-by: PauloMigAlmeida <paulo.miguel.almeida.rodenas@gmail.com>

src/main/java/org/kohsuke/github/GHAppCreateTokenBuilder.java

@@ -12,6 +12,7 @@ import static org.kohsuke.github.Previews.MACHINE_MAN;
  *
  * @author Paulo Miguel Almeida
  * @see GHAppInstallation#createToken(Map) GHAppInstallation#createToken(Map)
+ * @see GHAppInstallation#createToken() GHAppInstallation#createToken()
  */
 public class GHAppCreateTokenBuilder {
     private final GitHub root;
@@ -24,15 +25,13 @@ public class GHAppCreateTokenBuilder {
         this.root = root;
         this.apiUrlTail = apiUrlTail;
         this.builder = root.createRequest();
-        withPermissions(builder, permissions);
-        this.builder = new Requester(root);
     }
 
     @Preview
     @Deprecated
     GHAppCreateTokenBuilder(GitHub root, String apiUrlTail, Map<String, GHPermissionType> permissions) {
         this(root, apiUrlTail);
-        this.builder.withPermissions("permissions", permissions);
+        permissions(permissions);
     }
 
     /**
@@ -51,6 +50,25 @@ public class GHAppCreateTokenBuilder {
         return this;
     }
 
+    /**
+     * Set the permissions granted to the access token. The permissions object includes the permission names and their
+     * access type.
+     *
+     * @param permissions
+     *            Map containing the permission names and types.
+     * @return a GHAppCreateTokenBuilder
+     */
+    @Preview
+    @Deprecated
+    public GHAppCreateTokenBuilder permissions(Map<String, GHPermissionType> permissions) {
+        Map<String, String> retMap = new HashMap<>();
+        for (Map.Entry<String, GHPermissionType> entry : permissions.entrySet()) {
+            retMap.put(entry.getKey(), Requester.transformEnum(entry.getValue()));
+        }
+        builder.with("permissions", retMap);
+        return this;
+    }
+
     /**
      * Creates an app token with all the parameters.
      * <p>
@@ -70,12 +88,4 @@ public class GHAppCreateTokenBuilder {
                 .wrapUp(root);
     }
 
-    private static Requester withPermissions(Requester builder, Map<String, GHPermissionType> value) {
-        Map<String, String> retMap = new HashMap<String, String>();
-        for (Map.Entry<String, GHPermissionType> entry : value.entrySet()) {
-            retMap.put(entry.getKey(), Requester.transformEnum(entry.getValue()));
-        }
-        return builder.with("permissions", retMap);
-    }
-
 }

src/main/java/org/kohsuke/github/GHAppInstallation.java

@@ -287,7 +287,8 @@ public class GHAppInstallation extends GHObject {
      *
      * @param permissions
      *            map of permissions for the created token
-     * @return a GHAppCreateTokenBuilder on error
+     * @return a GHAppCreateTokenBuilder instance
+     * @deprecated Use {@link GHAppInstallation#createToken()} instead.
      */
     @Preview
     @Deprecated
@@ -302,7 +303,7 @@ public class GHAppInstallation extends GHObject {
      * You use the returned builder to set various properties, then call {@link GHAppCreateTokenBuilder#create()} to
      * finally create an access token.
      *
-     * @return a GHAppCreateTokenBuilder on error
+     * @return a GHAppCreateTokenBuilder instance
      */
     @Preview
     @Deprecated