Merge pull request #37 from JavaBWAPI/documentation

JavaDoc

Author: Bytekeeper

pom.xml

@@ -46,6 +46,16 @@
                     </execution>
                 </executions>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-site-plugin</artifactId>
+                <version>3.7.1</version>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-project-info-reports-plugin</artifactId>
+                <version>3.0.0</version>
+            </plugin>
             <plugin>
                 <groupId>org.codehaus.mojo</groupId>
                 <artifactId>exec-maven-plugin</artifactId>
@@ -73,6 +83,20 @@
         </plugins>
     </build>
 
+    <reporting>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <version>3.1.1</version>
+                <configuration>
+                    <additionalOptions>-Xdoclint:none</additionalOptions>
+                    <additionalJOption>-Xdoclint:none</additionalJOption>
+                </configuration>
+            </plugin>
+        </plugins>
+    </reporting>
+
     <dependencies>
         <!-- https://mvnrepository.com/artifact/net.java.dev.jna/jna -->
         <dependency>

src/main/java/bwapi/BWClient.java

@@ -2,6 +2,9 @@
 
 import java.util.Objects;
 
+/**
+ * Client class to connect to the game with.
+ */
 public class BWClient {
     private final BWEventListener eventListener;
 
@@ -14,10 +17,16 @@ public BWClient(final BWEventListener eventListener) {
         this.eventListener = eventListener;
     }
 
+    /**
+     * Get the {@link Game} instance of the currently running game.
+     */
     public Game getGame() {
         return handler == null ? null : handler.getGame();
     }
 
+    /**
+     * Start the game.
+     */
     public void startGame() {
         while (client == null) {
             try {

src/main/java/bwapi/BWEventListener.java

@@ -1,6 +1,8 @@
 package bwapi;
 
-
+/**
+ * Interface to extend to be given to a {@link BWClient}.
+ */
 public interface BWEventListener {
 
     void onStart();

src/main/java/bwapi/Bullet.java

@@ -4,6 +4,28 @@
 
 import java.util.Objects;
 
+/**
+ * An object representing a bullet or missile spawned from an attack.
+ *
+ * The Bullet interface allows you to detect bullets, missiles, and other types
+ * of non-melee attacks or special abilities that would normally be visible through
+ * human eyes (A lurker spike or a Queen's flying parasite), allowing quicker reaction
+ * to unavoidable consequences.
+ *
+ * For example, ordering medics to restore units that are about to receive a lockdown
+ * to compensate for latency and minimize its effects. You can't know entirely which unit
+ * will be receiving a lockdown unless you can detect the lockdown missile using the
+ * {@link Bullet} class.
+ *
+ * {@link Bullet} objects are re-used after they are destroyed, however their ID is updated when it
+ * represents a new Bullet.
+ *
+ * If {@link Flag#CompleteMapInformation} is disabled, then a {@link Bullet} is accessible if and only if
+ * it is visible. Otherwise if {@link Flag#CompleteMapInformation} is enabled, then all Bullets
+ * in the game are accessible.
+ * @see Game#getBullets
+ * @see Bullet#exists
+ */
 public class Bullet implements Comparable<Bullet> {
     private final BulletData bulletData;
     private final int id;
@@ -15,50 +37,136 @@ public class Bullet implements Comparable<Bullet> {
         this.game = game;
     }
 
+    /**
+     * Retrieves a unique identifier for the current {@link Bullet}.
+     *
+     * @return  An integer value containing the identifier.
+     */
     public int getID() {
         return id;
     }
 
+    /**
+     * Checks if the {@link Bullet} exists in the view of the BWAPI player.
+     *
+     * If {@link Flag#CompleteMapInformation} is disabled, and a {@link Bullet} is not visible, then the
+     * return value will be false regardless of the Bullet's true existence. This is because
+     * absolutely no state information on invisible enemy bullets is made available to the AI.
+     *
+     * If {@link Flag#CompleteMapInformation} is enabled, then this function is accurate for all
+     * {@link Bullet} information.
+     * 
+     * @return true if the bullet exists or is visible, false if the bullet was destroyed or has gone out of scope.
+     * @see #isVisible
+     * @see Unit#exists
+     */
     public boolean exists() {
         return bulletData.getExists();
     }
 
+    /**
+     * Retrieves the {@link Player} interface that owns the Bullet.
+     *
+     * @return  The owning {@link Player} object. Returns null if the {@link Player} object for this {@link Bullet} is inaccessible.
+     */
     public Player getPlayer() {
         return game.getPlayer(bulletData.getPlayer());
     }
 
+    /**
+     * Retrieves the type of this {@link Bullet}.
+     *
+     * @return  A {@link BulletType} representing the Bullet's type. Returns {@link BulletType#Unknown} if the {@link Bullet} is inaccessible.
+     */
     public BulletType getType() {
         return BulletType.idToEnum[bulletData.getType()];
     }
 
+    /**
+     * Retrieves the {@link Unit} that the {@link Bullet} spawned from.
+     *
+     * @return  The owning {@link Unit} object. Returns null if the source can not be identified or is inaccessible.
+     * @see #getTarget
+     */
     public Unit getSource() {
         return game.getUnit(bulletData.getSource());
     }
 
+    /**
+     * Retrieves the Bullet's current position.
+     *
+     * @return  A {@link Position} containing the Bullet's current coordinates. Returns {@link Position#Unknown} if the {@link Bullet} is inaccessible.
+     * @see #getTargetPosition
+     */
     public Position getPosition() {
         return new Position(bulletData.getPositionX(), bulletData.getPositionY());
     }
 
+    /**
+     * Retrieve's the direction the {@link Bullet} is facing. If the angle is 0, then
+     * the {@link Bullet} is facing right.
+     *
+     * @return  A double representing the direction the {@link Bullet} is facing. Returns 0.0 if the bullet is inaccessible.
+     */
     public double getAngle() {
         return bulletData.getAngle();
     }
 
+    /**
+     * Retrieves the X component of the Bullet's velocity, measured in pixels per frame.
+     *
+     * @return  A double representing the number of pixels moved on the X axis per frame. Returns 0.0 if the {@link Bullet} is inaccessible.
+     *
+     * @see #getVelocityY
+     * @see #getAngle
+     */
     public double getVelocityX() {
         return bulletData.getVelocityX();
     }
 
+    /**
+     * Retrieves the Y component of the Bullet's velocity, measured in pixels per frame.
+     *
+     * @return  A double representing the number of pixels moved on the Y axis per frame. Returns 0.0 if the {@link Bullet} is inaccessible.
+     *
+     * @see #getVelocityX
+     * @see #getAngle
+     */
     public double getVelocityY() {
         return bulletData.getVelocityY();
     }
 
+    /**
+     * Retrieves the Unit interface that the {@link Bullet} is heading to.
+     *
+     * @return  The target Unit object, if one exists. Returns null if the Bullet's target {@link Unit} is inaccessible, the {@link Bullet} is targetting the ground, or if the {@link Bullet} itself is inaccessible.
+     * @see #getTargetPosition
+     * @see #getSource
+     */
     public Unit getTarget() {
         return game.getUnit(bulletData.getTarget());
     }
 
+    /**
+     * Retrieves the target position that the {@link Bullet} is heading to.
+     *
+     * @return  A {@link Position} indicating where the {@link Bullet} is headed. Returns {@link Position#Unknown} if the bullet is inaccessible.
+     * @see #getTarget
+     * @see #getPosition
+     */
     public Position getTargetPosition() {
         return new Position(bulletData.getTargetPositionX(), bulletData.getTargetPositionY());
     }
 
+    /**
+     * Retrieves the timer that indicates the Bullet's life span.
+     *
+     * Bullets are not permanent objects, so they will often have a limited life span.
+     * This life span is measured in frames. Normally a Bullet will reach its target
+     * before being removed.
+     *
+     * @return  An integer representing the remaining number of frames until the {@link Bullet} self-destructs. Returns 0 if the {@link Bullet} is inaccessible.
+     */
     public int getRemoveTimer() {
         return bulletData.getRemoveTimer();
     }
@@ -67,7 +175,17 @@ public boolean isVisible() {
         return isVisible(game.self());
     }
 
+    /**
+     * Retrieves the visibility state of the Bullet.
+     *
+     * @param player If this parameter is specified, then the Bullet's visibility to the given player is checked. If this parameter is omitted, then a default value of null is used, which will check if the BWAPI player has vision of the {@link Bullet}.
+     *
+     * @return true if the {@link Bullet} is visible to the specified player, false if the {@link Bullet} is not visible to the specified player.
+     */
     public boolean isVisible(final Player player) {
+        if (player == null) {
+            return isVisible();
+        }
         return bulletData.isVisible(player.getID());
     }
 

src/main/java/bwapi/BulletType.java

@@ -2,6 +2,11 @@
 
 import java.util.Arrays;
 
+/**
+ * This enum represents a type of bullet.
+ *
+ * Internally, these are the same IDs as flingy types in Broodwar.
+ */
 public enum BulletType {
     Melee(0),
 

src/main/java/bwapi/Color.java

@@ -3,18 +3,60 @@
 
 import java.util.Objects;
 
+/**
+ * The Color object is used in drawing routines to specify the color to use.
+ *
+ * Starcraft uses a 256 color palette for rendering. Thus, the colors available are
+ * limited to this palette.
+ */
 public class Color {
+    /**
+     * The default color for Player 1.
+     */
     public final static Color Red = new Color(111);
+    /**
+     * The default color for Player 2.
+     */
     public final static Color Blue = new Color(165);
+    /**
+     * The default color for Player 3.
+     */
     public final static Color Teal = new Color(159);
+    /**
+     * The default color for Player 4.
+     */
     public final static Color Purple = new Color(164);
+    /**
+     * The default color for Player 5.
+     */
     public final static Color Orange = new Color(156);
+    /**
+     * The default color for Player 6.
+     */
     public final static Color Brown = new Color(19);
+    /**
+     * A bright white. Note that this is lighter than Player 7's white.
+     */
     public final static Color White = new Color(255);
+    /**
+     * The default color for Player 8.
+     */
     public final static Color Yellow = new Color(135);
+    /**
+     * The alternate color for Player 7 on Ice tilesets.
+     */
     public final static Color Green = new Color(117);
+    /**
+     * The default color for Neutral (Player 12).
+     */
     public final static Color Cyan = new Color(128);
+    /**
+     * The color black.
+     */
     public final static Color Black = new Color(0);
+    /**
+     * The color grey.
+     */
     public final static Color Grey = new Color(74);
 
     private static final RGBQUAD RGBRESERVE = new RGBQUAD(0, 0, 0, 0xFF);
@@ -66,10 +108,25 @@ RGBRESERVE, RGBRESERVE, RGBRESERVE, RGBRESERVE, RGBRESERVE, RGBRESERVE, RGBRESER
     }
     public final int id;
 
-    public Color(final int r, final int g, final int b) {
-        id = getRGBIndex(r, g, b);
+    /**
+     * A constructor that uses the color index in the palette that is closest to the
+     * given rgb values. On its first call, the colors in the palette will be sorted for fast indexing.
+     *
+     * This function computes the distance of the RGB values and may not be accurate.
+     *
+     * @param red The amount of red.
+     * @param green The amount of green.
+     * @param blue The amount of blue.
+     */
+    public Color(final int red, final int green, final int blue) {
+        id = getRGBIndex(red, green, blue);
     }
 
+    /**
+     * A constructor that uses the color at the specified palette index.
+     *
+     * @param id The index of the color in the 256-color palette.
+     */
     public Color(final int id) {
         this.id = id;
     }

src/main/java/bwapi/CommandType.java

@@ -2,6 +2,9 @@
 
 import java.util.Arrays;
 
+/**
+ * Used in {@link UnitCommand}.
+ */
 public enum CommandType {
     None(0),
     SetScreenPosition(1),