Cleaned up some doc blocks (#352)

Author: mashurex

src/main/java/com/pokegoapi/api/gym/Battle.java

@@ -56,7 +56,9 @@ public class Battle {
 
 	/**
 	 * New battle to track the state of a battle.
-	 *
+	 * @param api The api instance to submit requests with.
+     * @param team The Pokemon to use for attacking in the battle.
+     * @param gym The Gym to fight at.
 	 */
 	public Battle(PokemonGo api, Pokemon[] team, Gym gym) {
 		this.team = team;
@@ -75,6 +77,8 @@ public Battle(PokemonGo api, Pokemon[] team, Gym gym) {
 	 * Start a battle.
 	 *
 	 * @return Result of the attempt to start
+     * @throws LoginFailedException  if the login failed
+     * @throws RemoteServerException When a buffer exception is thrown
 	 */
 	public Result start() throws LoginFailedException, RemoteServerException {
 
@@ -120,6 +124,8 @@ public Result start() throws LoginFailedException, RemoteServerException {
 	 *
 	 * @param times the amount of times to attack
 	 * @return Battle
+     * @throws LoginFailedException  if the login failed
+     * @throws RemoteServerException When a buffer exception is thrown
 	 */
 	public AttackGymResponse attack(int times) throws LoginFailedException, RemoteServerException {
 

src/main/java/com/pokegoapi/api/gym/Gym.java

@@ -44,7 +44,8 @@ public class Gym {
 
 	/**
 	 * Gym object.
-	 *
+	 * @param api The api object to use for requests.
+     * @param proto The FortData to populate the Gym with.
 	 */
 	public Gym(PokemonGo api, FortData proto) {
 		this.api = api;
@@ -153,6 +154,8 @@ public List<GymMembership> getGymMembers() throws LoginFailedException, RemoteSe
 	 * Get a list of pokemon defending this gym.
 	 *
 	 * @return List of pokemon
+     * @throws LoginFailedException  if the login failed
+     * @throws RemoteServerException When a buffer exception is thrown
 	 */
 	public List<PokemonData> getDefendingPokemon() throws LoginFailedException, RemoteServerException {
 		List<PokemonData> data = new ArrayList<PokemonData>();

src/main/java/com/pokegoapi/api/map/Map.java

@@ -97,6 +97,8 @@ public void clearCache() {
 	 * Returns a list of catchable pokemon around the current location.
 	 *
 	 * @return a List of CatchablePokemon at your current location
+     * @throws LoginFailedException  if the login failed
+     * @throws RemoteServerException When a buffer exception is thrown
 	 */
 	public List<CatchablePokemon> getCatchablePokemon() throws LoginFailedException, RemoteServerException {
 		Set<CatchablePokemon> catchablePokemons = new HashSet<>();
@@ -124,6 +126,8 @@ public List<CatchablePokemon> getCatchablePokemon() throws LoginFailedException,
 	 * Returns a list of nearby pokemon (non-catchable).
 	 *
 	 * @return a List of NearbyPokemon at your current location
+     * @throws LoginFailedException  if the login failed
+     * @throws RemoteServerException When a buffer exception is thrown
 	 */
 	public List<NearbyPokemon> getNearbyPokemon() throws LoginFailedException, RemoteServerException {
 		List<NearbyPokemon> pokemons = new ArrayList<>();
@@ -140,6 +144,8 @@ public List<NearbyPokemon> getNearbyPokemon() throws LoginFailedException, Remot
 	 * Returns a list of spawn points.
 	 *
 	 * @return list of spawn points
+     * @throws LoginFailedException  if the login failed
+     * @throws RemoteServerException When a buffer exception is thrown
 	 */
 	public List<Point> getSpawnPoints() throws LoginFailedException, RemoteServerException {
 		List<Point> points = new ArrayList<>();
@@ -156,6 +162,8 @@ public List<Point> getSpawnPoints() throws LoginFailedException, RemoteServerExc
 	 * Get a list of gyms near the current location.
 	 *
 	 * @return List of gyms
+     * @throws LoginFailedException  if the login failed
+     * @throws RemoteServerException When a buffer exception is thrown
 	 */
 	public List<Gym> getGyms() throws LoginFailedException, RemoteServerException {
 		List<Gym> gyms = new ArrayList<>();
@@ -174,6 +182,8 @@ public List<Gym> getGyms() throws LoginFailedException, RemoteServerException {
 	 * Returns a list of decimated spawn points at current location.
 	 *
 	 * @return list of spawn points
+     * @throws LoginFailedException  if the login failed
+     * @throws RemoteServerException When a buffer exception is thrown
 	 */
 	public List<Point> getDecimatedSpawnPoints() throws LoginFailedException, RemoteServerException {
 		List<Point> points = new ArrayList<>();
@@ -190,6 +200,8 @@ public List<Point> getDecimatedSpawnPoints() throws LoginFailedException, Remote
 	 * Returns MapObjects around your current location.
 	 *
 	 * @return MapObjects at your current location
+     * @throws LoginFailedException  if the login failed
+     * @throws RemoteServerException When a buffer exception is thrown
 	 */
 	public MapObjects getMapObjects() throws LoginFailedException, RemoteServerException {
 		return getMapObjects(9);
@@ -200,6 +212,9 @@ public MapObjects getMapObjects() throws LoginFailedException, RemoteServerExcep
 	 *
 	 * @param width width
 	 * @return MapObjects at your current location
+     *
+     * @throws LoginFailedException If login fails.
+     * @throws RemoteServerException If request errors occurred.
 	 */
 	public MapObjects getMapObjects(int width) throws LoginFailedException, RemoteServerException {
 		return getMapObjects(
@@ -218,6 +233,8 @@ public MapObjects getMapObjects(int width) throws LoginFailedException, RemoteSe
 	 * @param latitude  latitude
 	 * @param longitude longitude
 	 * @return MapObjects in the given cells
+     * @throws LoginFailedException  if the login failed
+     * @throws RemoteServerException When a buffer exception is thrown
 	 */
 	@Deprecated
 	public MapObjects getMapObjects(double latitude, double longitude)
@@ -232,6 +249,8 @@ public MapObjects getMapObjects(double latitude, double longitude)
 	 * @param latitude  latitude
 	 * @param longitude longitude
 	 * @return MapObjects in the given cells
+     * @throws LoginFailedException  if the login failed
+     * @throws RemoteServerException When a buffer exception is thrown
 	 */
 	@Deprecated
 	public MapObjects getMapObjects(List<Long> cellIds, double latitude, double longitude)
@@ -246,6 +265,8 @@ public MapObjects getMapObjects(List<Long> cellIds, double latitude, double long
 	 * @param longitude longitude
 	 * @param width     width
 	 * @return MapObjects in the given cells
+     * @throws LoginFailedException  if the login failed
+     * @throws RemoteServerException When a buffer exception is thrown
 	 */
 	@Deprecated
 	public MapObjects getMapObjects(double latitude, double longitude, int width)
@@ -259,7 +280,10 @@ public MapObjects getMapObjects(double latitude, double longitude, int width)
 	 * @param cellIds   cellIds
 	 * @param latitude  latitude
 	 * @param longitude longitude
+     * @param altitude altitude
 	 * @return MapObjects in the given cells
+     * @throws LoginFailedException  if the login failed
+     * @throws RemoteServerException When a buffer exception is thrown
 	 */
 	@Deprecated
 	public MapObjects getMapObjects(List<Long> cellIds, double latitude, double longitude, double altitude)
@@ -275,6 +299,8 @@ public MapObjects getMapObjects(List<Long> cellIds, double latitude, double long
 	 *
 	 * @param cellIds List of cellId
 	 * @return MapObjects in the given cells
+     * @throws LoginFailedException  if the login failed
+     * @throws RemoteServerException When a buffer exception is thrown
 	 */
 	public MapObjects getMapObjects(List<Long> cellIds) throws LoginFailedException, RemoteServerException {
 		GetMapObjectsMessage.Builder builder = GetMapObjectsMessage.newBuilder();

src/main/java/com/pokegoapi/api/map/MapObjects.java

@@ -164,8 +164,7 @@ public boolean isComplete() {
 
 	/**
 	 * updates the object.
-	 *
-	 *
+	 * @param other Update this {@link MapObjects} data with the provided data.
 	 */
 	public void update(MapObjects other) {
 

src/main/java/com/pokegoapi/api/map/fort/Pokestop.java

@@ -194,6 +194,8 @@ public boolean hasLurePokemon() {
 	/**
 	 * Returns whether this pokestop has an active lure.
 	 * @return lure status
+     * @throws LoginFailedException If login failed.
+     * @throws RemoteServerException If server communications failed.
 	 */
 	public boolean hasLure() throws LoginFailedException, RemoteServerException {
 

src/main/java/com/pokegoapi/api/player/PlayerProfile.java

@@ -195,7 +195,7 @@ public void addCurrency(String name, int amount) throws InvalidCurrencyException
 	 * Check and equip badges.
 	 *
 	 * @throws LoginFailedException  if the login failed
-	 * @throws InvalidCurrencyException the invalid currency exception
+	 * @throws RemoteServerException When a buffer exception is thrown
 	 */
 
 	public void checkAndEquipBadges() throws LoginFailedException, RemoteServerException {

src/main/java/com/pokegoapi/api/pokemon/Pokemon.java

@@ -411,6 +411,7 @@ public float getLevel() {
 	 * Calculate the maximum CP for this individual pokemon
 	 *
 	 * @return The maximum CP for this pokemon
+     * @throws NoSuchItemException If the PokemonId value cannot be found in the {@link PokemonMetaRegistry}.
 	 */
 	public int getMaxCp() throws NoSuchItemException {
 		PokemonMeta pokemonMeta = PokemonMetaRegistry.getMeta(proto.getPokemonId());
@@ -427,6 +428,7 @@ public int getMaxCp() throws NoSuchItemException {
 	 * Calculates the absolute maximum CP for all pokemons with this PokemonId
 	 *
 	 * @return The absolute maximum CP
+     * @throws NoSuchItemException If the PokemonId value cannot be found in the {@link PokemonMetaRegistry}.
 	 */
 	public int getAbsoluteMaxCp() throws NoSuchItemException {
 		return getAbsoluteMaxCp(proto.getPokemonId());
@@ -435,7 +437,9 @@ public int getAbsoluteMaxCp() throws NoSuchItemException {
 
 	/**
 	 * Static helper to get the absolute maximum CP for pokemons with their PokemonId.
-	 * +	 * @return The absolute maximum CP
+     * @param id The {@link POGOProtos.Enums.PokemonIdOuterClass.PokemonId} of the Pokemon to get CP for.
+	 * @return The absolute maximum CP
+     * @throws NoSuchItemException If the PokemonId value cannot be found in the {@link PokemonMetaRegistry}.
 	 */
 	public static int getAbsoluteMaxCp(PokemonIdOuterClass.PokemonId id) throws NoSuchItemException {
 		PokemonMeta pokemonMeta = PokemonMetaRegistry.getMeta(id);
@@ -499,6 +503,8 @@ public boolean isFainted() {
 	 * Heal a pokemon, using various fallbacks for potions
 	 *
 	 * @return Result, ERROR_CANNOT_USE if the requirements arent met
+     * @throws LoginFailedException If login failed.
+     * @throws RemoteServerException If server communication issues occurred.
 	 */
 	public UseItemPotionResponseOuterClass.UseItemPotionResponse.Result heal()
 			throws LoginFailedException, RemoteServerException {
@@ -522,10 +528,12 @@ public UseItemPotionResponseOuterClass.UseItemPotionResponse.Result heal()
 	}
 
 	/**
-	 * use a potion on that pokemon. Will check if there is enough potions & if the pokemon need
+	 * use a potion on that pokemon. Will check if there is enough potions and if the pokemon need
 	 * to be healed.
-	 *
-	 * @return Result, ERROR_CANNOT_USE if the requirements arent met
+	 * @param itemId {@link ItemId} of the potion to use.
+	 * @return Result, ERROR_CANNOT_USE if the requirements aren't met
+     * @throws LoginFailedException If login failed.
+     * @throws RemoteServerException If server communications failed.
 	 */
 	public UseItemPotionResponseOuterClass.UseItemPotionResponse.Result usePotion(ItemId itemId)
 			throws LoginFailedException, RemoteServerException {
@@ -560,6 +568,8 @@ public UseItemPotionResponseOuterClass.UseItemPotionResponse.Result usePotion(It
 	 * Revive a pokemon, using various fallbacks for revive items
 	 *
 	 * @return Result, ERROR_CANNOT_USE if the requirements arent met
+     * @throws LoginFailedException If login failed.
+     * @throws RemoteServerException If server communications failed.
 	 */
 	public UseItemReviveResponseOuterClass.UseItemReviveResponse.Result revive()
 			throws LoginFailedException, RemoteServerException {
@@ -577,10 +587,12 @@ public UseItemReviveResponseOuterClass.UseItemReviveResponse.Result revive()
 	}
 
 	/**
-	 * Use a revive item on the pokemon. Will check if there is enough revive & if the pokemon need
+	 * Use a revive item on the pokemon. Will check if there is enough revive & if the pokemon need
 	 * to be revived.
-	 *
+	 * @param itemId {@link ItemId} of the Revive to use.
 	 * @return Result, ERROR_CANNOT_USE if the requirements arent met
+     * @throws LoginFailedException If login failed.
+     * @throws RemoteServerException If server communications failed.
 	 */
 	public UseItemReviveResponseOuterClass.UseItemReviveResponse.Result useRevive(ItemId itemId)
 			throws LoginFailedException, RemoteServerException {

src/main/java/com/pokegoapi/api/settings/Settings.java

@@ -60,6 +60,10 @@ public class Settings {
 	/**
 	 * Settings object that hold different configuration aspect of the game.
 	 * Can be used to simulate the real app behaviour.
+     *
+     * @param api api instance
+     * @throws LoginFailedException If login failed.
+     * @throws RemoteServerException If server communications failed.
 	 */
 	public Settings(PokemonGo api) throws LoginFailedException, RemoteServerException {
 		this.api = api;

src/main/java/com/pokegoapi/examples/CatchPokemonAtAreaExample.java

@@ -50,6 +50,7 @@ public class CatchPokemonAtAreaExample {
 
 	/**
 	 * Catches a pokemon at an area.
+     * @param args args
 	 */
 	public static void main(String[] args) {
 		OkHttpClient http = new OkHttpClient();