fix Bullet javadoc

Author: JasperGeurtz

src/main/java/bwapi/Bullet.java

@@ -15,15 +15,15 @@
  * 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
- * Bullet class.
+ * {@link Bullet} class.
  *
- * Bullet objects are re-used after they are destroyed, however their ID is updated when it
+ * {@link Bullet} objects are re-used after they are destroyed, however their ID is updated when it
  * represents a new Bullet.
  *
- * If Flag#CompleteMapInformation is disabled, then a Bullet is accessible if and only if
- * it is visible. Otherwise if Flag#CompleteMapInformation is enabled, then all Bullets
+ * 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, Bullet#exists
+ * @see {@link Game#getBullets}, {@link Bullet#exists}
  */
 public class Bullet implements Comparable<Bullet> {
     private final BulletData bulletData;
@@ -37,7 +37,7 @@ public class Bullet implements Comparable<Bullet> {
     }
 
     /**
-     * Retrieves a unique identifier for the current Bullet.
+     * Retrieves a unique identifier for the current {@link Bullet}.
      *
      * @return  An integer value containing the identifier.
      */
@@ -46,52 +46,45 @@ public int getID() {
     }
 
     /**
-     * Checks if the Bullet exists in the view of the BWAPI player.
+     * Checks if the {@link Bullet} exists in the view of the BWAPI player.
      *
-     * @retval true If the bullet exists or is visible.
-     * @retval false If the bullet was destroyed or has gone out of scope.
-     *
-     * If Flag#CompleteMapInformation is disabled, and a Bullet is not visible, then the
+     * 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 Flag#CompleteMapInformation is enabled, then this function is accurate for all
-     * Bullet information.
-     * @see isVisible, Unit#exists
+     * 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 {@link #isVisible}, {@link Unit#exists}
      */
     public boolean exists() {
         return bulletData.getExists();
     }
 
     /**
-     * Retrieves the Player interface that owns the Bullet.
-     *
-     * @retval null If the Player object for this Bullet is inaccessible.
+     * Retrieves the {@link Player} interface that owns the Bullet.
      *
-     * @return  The owning Player object.
+     * @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 Bullet.
-     *
-     * @retval BulletType.Unknown if the Bullet is inaccessible.
+     * Retrieves the type of this {@link Bullet}.
      *
-     * @return  A BulletType representing the Bullet's type.
+     * @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 Unit interface that the Bullet spawned from.
+     * Retrieves the {@link Unit} that the {@link Bullet} spawned from.
      *
-     * @retval null If the source can not be identified or is inaccessible.
-     *
-     * @return  The owning Unit object.
-     * @see getTarget
+     * @return  The owning {@link Unit} object. Returns null if the source can not be identified or is inaccessible.
+     * @see {@link #getTarget}
      */
     public Unit getSource() {
         return game.getUnit(bulletData.getSource());
@@ -100,22 +93,18 @@ public Unit getSource() {
     /**
      * Retrieves the Bullet's current position.
      *
-     * @retval Position.Unknown If the Bullet is inaccessible.
-     *
-     * @return  A Position containing the Bullet's current coordinates.
-     * @see getTargetPosition
+     * @return  A {@link Position} containing the Bullet's current coordinates. Returns {@link Position#Unknown} if the {@link Bullet} is inaccessible.
+     * @see {@link #getTargetPosition}
      */
     public Position getPosition() {
         return new Position(bulletData.getPositionX(), bulletData.getPositionY());
     }
 
     /**
-     * Retrieve's the direction the Bullet is facing. If the angle is 0, then
-     * the Bullet is facing right.
-     *
-     * @retval 0.0 If the bullet is inaccessible.
+     * 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 Bullet is facing.
+     * @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();
@@ -124,11 +113,9 @@ public double getAngle() {
     /**
      * Retrieves the X component of the Bullet's velocity, measured in pixels per frame.
      *
-     * @retval 0.0 if the Bullet is inaccessible.
+     * @return  A double representing the number of pixels moved on the X axis per frame. Returns 0.0 if the {@link Bullet} is inaccessible.
      *
-     * @return  A double representing the number of pixels moved on the X axis per frame.
-     *
-     * @see getVelocityY, getAngle
+     * @see {@link #getVelocityY}, {@link #getAngle}
      */
     public double getVelocityX() {
         return bulletData.getVelocityX();
@@ -137,36 +124,29 @@ public double getVelocityX() {
     /**
      * Retrieves the Y component of the Bullet's velocity, measured in pixels per frame.
      *
-     * @retval 0.0 if the Bullet is inaccessible.
-     *
-     * @return  A double representing the number of pixels moved on the Y axis 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, getAngle
+     * @see {@link #getVelocityX}, {@link #getAngle}
      */
     public double getVelocityY() {
         return bulletData.getVelocityY();
     }
 
     /**
-     * Retrieves the Unit interface that the Bullet is heading to.
-     *
-     * @retval null If the Bullet's target Unit is inaccessible, the Bullet is targetting the
-     * ground, or if the Bullet itself is inaccessible.
+     * Retrieves the Unit interface that the {@link Bullet} is heading to.
      *
-     * @return  The target Unit object, if one exists.
-     * @see getTargetPosition, getSource
+     * @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 {@link #getTargetPosition}, {@link #getSource}
      */
     public Unit getTarget() {
         return game.getUnit(bulletData.getTarget());
     }
 
     /**
-     * Retrieves the target position that the Bullet is heading to.
+     * Retrieves the target position that the {@link Bullet} is heading to.
      *
-     * @retval Position.Unknown If the bullet is inaccessible.
-     *
-     * @return  A Position indicating where the Bullet is headed.
-     * @see getTarget, getPosition
+     * @return  A {@link Position} indicating where the {@link Bullet} is headed. Returns {@link Position#Unknown} if the bullet is inaccessible.
+     * @see {@link #getTarget}, {@link #getPosition}
      */
     public Position getTargetPosition() {
         return new Position(bulletData.getTargetPositionX(), bulletData.getTargetPositionY());
@@ -179,9 +159,7 @@ public Position getTargetPosition() {
      * This life span is measured in frames. Normally a Bullet will reach its target
      * before being removed.
      *
-     * @retval 0 If the Bullet is inaccessible.
-     *
-     * @return  An integer representing the remaining number of frames until the Bullet self-destructs.
+     * @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();
@@ -194,16 +172,14 @@ public boolean isVisible() {
     /**
      * 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 Bullet.
-     *
-     * @note If \c player is null and game.self() is also null, then the visibility of
-     * the Bullet is determined by checking if at least one other player has vision 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}.
      *
-     * @retval true If the Bullet is visible to the specified player.
-     * @retval false If the Bullet is not visible to the specified player.
+     * @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/Game.java

@@ -550,7 +550,7 @@ public int getReplayFrameCount() {
      *
      * Example:
      * @return Logical frames per second that the game is currently running at as an integer.
-     * @see getAverageFPS
+     * @see Game#getAverageFPS
      */
     public int getFPS() {
         return gameData.getFps();
@@ -561,7 +561,7 @@ public int getFPS() {
      *
      * @return Average logical frames per second that the game is currently running at as a
      * double.
-     * @see getFPS
+     * @see {@link #getFPS}
      */
     public double getAverageFPS() {
         return gameData.getAverageFPS();
@@ -571,7 +571,7 @@ public double getAverageFPS() {
      * Retrieves the position of the user's mouse on the screen, in Position coordinates.
      *
      * @return Position indicating the location of the mouse.
-     * @retval Position.Unknown if Flag#UserInput is disabled.
+     * @retval Position.Unknown if {@link Flag#UserInput} is disabled.
      */
     public Position getMousePosition() {
         return new Position(gameData.getMouseX(), gameData.getMouseY());