BETA: Added two new methods and updating JavaDocs:

	* `public L2PcInstance getRandomPartyMember(L2PcInstance player, L2Npc npc)`
	* `public boolean checkPartyMember(L2PcInstance player, L2Npc npc)`
Patch by: jurchiks
Reviewed by: Adry_85, UnAfraid, Nos

L2J_Server_BETA/java/com/l2jserver/gameserver/model/L2Object.java

@@ -445,7 +445,7 @@ public abstract class L2Object implements IIdentifiable, INamable, ISpawnable, I
 	}
 	
 	/**
-	 * @return {@code true} if object is instance of L2Attackable
+	 * @return {@code true} if object is instance of L2Character
 	 */
 	public boolean isCharacter()
 	{
@@ -747,12 +747,12 @@ public abstract class L2Object implements IIdentifiable, INamable, ISpawnable, I
 	 * Calculates the angle in degrees from this object to the given object.<br>
 	 * The return value can be described as how much this object has to turn<br>
 	 * to have the given object directly in front of it.
-	 * @param to
-	 * @return the angle this onject has to turn to have the given object in front of it
+	 * @param target the object to which to calculate the angle
+	 * @return the angle this object has to turn to have the given object in front of it
 	 */
-	public double calculateDirectionTo(ILocational to)
+	public double calculateDirectionTo(ILocational target)
 	{
-		int heading = Util.calculateHeadingFrom(this, to) - this.getHeading();
+		int heading = Util.calculateHeadingFrom(this, target) - this.getHeading();
 		if (heading < 0)
 		{
 			heading = 65535 + heading;

L2J_Server_BETA/java/com/l2jserver/gameserver/model/quest/Quest.java

@@ -319,7 +319,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	 * @param name the name of the quest timer to get
 	 * @param npc the NPC associated with the quest timer to get
 	 * @param player the player associated with the quest timer to get
-	 * @return the quest timer that matches the parameters of this function or {@code null} if nothing was found
+	 * @return the quest timer that matches the specified parameters or {@code null} if nothing was found
 	 */
 	public QuestTimer getQuestTimer(String name, L2Npc npc, L2PcInstance player)
 	{
@@ -1445,7 +1445,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 			{
 				while (rs.next())
 				{
-					// Get the ID of the quest and Id of its state
+					// Get the ID of the quest and its state
 					String questId = rs.getString("name");
 					String statename = rs.getString("value");
 					
@@ -1705,14 +1705,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Update informations regarding quest in database.<br>
-	 * Actions:<br>
-	 * <ul>
-	 * <li>Get ID state of the quest recorded in object qs</li>
-	 * <li>Test if quest is completed. If true, add a star (*) before the ID state</li>
-	 * <li>Save in database the ID state (with or without the star) for the variable called "&lt;state&gt;" of the quest</li>
-	 * </ul>
-	 * @param qs the quest state
+	 * Update a quest state record of the specified quest state in database.
+	 * @param qs the {@link QuestState} object whose data to update in the database
 	 */
 	public static void updateQuestInDb(QuestState qs)
 	{
@@ -1750,7 +1744,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	/**
 	 * Add this quest to the list of quests that the passed mob will respond to for the specified Event type.
 	 * @param eventType type of event being registered
-	 * @param npcId NPC ID to register
+	 * @param npcId the ID of the NPC to register
 	 */
 	public void addEventId(QuestEventType eventType, int npcId)
 	{
@@ -1772,7 +1766,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	/**
 	 * Add this quest to the list of quests that the passed mob will respond to for the specified Event type.
 	 * @param eventType type of event being registered
-	 * @param npcIds NPC IDs to register
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addEventId(QuestEventType eventType, int... npcIds)
 	{
@@ -1785,7 +1779,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	/**
 	 * Add this quest to the list of quests that the passed mob will respond to for the specified Event type.
 	 * @param eventType type of event being registered
-	 * @param npcIds NPC IDs to register
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addEventId(QuestEventType eventType, Collection<Integer> npcIds)
 	{
@@ -1823,7 +1817,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	
 	/**
 	 * Add the quest to the NPC's startQuest
-	 * @param npcIds
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addStartNpc(int... npcIds)
 	{
@@ -1832,7 +1826,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	
 	/**
 	 * Add the quest to the NPC's startQuest
-	 * @param npcIds
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addStartNpc(Collection<Integer> npcIds)
 	{
@@ -1840,8 +1834,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Add the quest to the NPC's first-talk (default action dialog)
-	 * @param npcIds
+	 * Add the quest to the NPC's first-talk (default action dialog).
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addFirstTalkId(int... npcIds)
 	{
@@ -1849,8 +1843,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Add the quest to the NPC's first-talk (default action dialog)
-	 * @param npcIds
+	 * Add the quest to the NPC's first-talk (default action dialog).
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addFirstTalkId(Collection<Integer> npcIds)
 	{
@@ -1858,8 +1852,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Add the NPC to the AcquireSkill dialog
-	 * @param npcIds
+	 * Add the NPC to the AcquireSkill dialog.
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addAcquireSkillId(int... npcIds)
 	{
@@ -1867,8 +1861,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Add the NPC to the AcquireSkill dialog
-	 * @param npcIds
+	 * Add the NPC to the AcquireSkill dialog.
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addAcquireSkillId(Collection<Integer> npcIds)
 	{
@@ -1876,8 +1870,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Add this quest to the list of quests that the passed mob will respond to for Attack Events.
-	 * @param npcIds
+	 * Add this quest to the list of quests that the passed mob will respond to for attack events.
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addAttackId(int... npcIds)
 	{
@@ -1885,8 +1879,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Add this quest to the list of quests that the passed mob will respond to for Attack Events.
-	 * @param npcIds
+	 * Add this quest to the list of quests that the passed mob will respond to for attack events.
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addAttackId(Collection<Integer> npcIds)
 	{
@@ -1894,7 +1888,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Add this quest to the list of quests that the passed mob will respond to for Kill Events.
+	 * Add this quest to the list of quests that the passed mob will respond to for kill events.
 	 * @param killIds
 	 */
 	public void addKillId(int... killIds)
@@ -1913,7 +1907,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	
 	/**
 	 * Add this quest to the list of quests that the passed npc will respond to for Talk Events.
-	 * @param npcIds Id of the NPC
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addTalkId(int... npcIds)
 	{
@@ -1926,8 +1920,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Add this quest to the list of quests that the passed npc will respond to for Spawn Events.
-	 * @param npcIds Id of the NPC
+	 * Add this quest to the list of quests that the passed npc will respond to for spawn events.
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addSpawnId(int... npcIds)
 	{
@@ -1935,8 +1929,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Add this quest to the list of quests that the passed npc will respond to for Spawn Events.
-	 * @param npcIds ID of the NPC
+	 * Add this quest to the list of quests that the passed npc will respond to for spawn events.
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addSpawnId(Collection<Integer> npcIds)
 	{
@@ -1944,8 +1938,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Add this quest to the list of quests that the passed npc will respond to for Skill-See Events.
-	 * @param npcIds ID of the NPC
+	 * Add this quest to the list of quests that the passed npc will respond to for skill see events.
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addSkillSeeId(int... npcIds)
 	{
@@ -1953,8 +1947,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Add this quest to the list of quests that the passed npc will respond to for Skill-See Events.
-	 * @param npcIds ID of the NPC
+	 * Add this quest to the list of quests that the passed npc will respond to for skill see events.
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addSkillSeeId(Collection<Integer> npcIds)
 	{
@@ -1962,7 +1956,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * @param npcIds
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addSpellFinishedId(int... npcIds)
 	{
@@ -1970,7 +1964,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * @param npcIds
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addSpellFinishedId(Collection<Integer> npcIds)
 	{
@@ -1978,7 +1972,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * @param npcIds
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addTrapActionId(int... npcIds)
 	{
@@ -1986,7 +1980,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * @param npcIds
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addTrapActionId(Collection<Integer> npcIds)
 	{
@@ -1994,8 +1988,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Add this quest to the list of quests that the passed npc will respond to for Faction Call Events.
-	 * @param npcIds ID of the NPC
+	 * Add this quest to the list of quests that the passed npc will respond to for faction call events.
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addFactionCallId(int... npcIds)
 	{
@@ -2003,8 +1997,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Add this quest to the list of quests that the passed npc will respond to for Faction Call Events.
-	 * @param npcIds ID of the NPC
+	 * Add this quest to the list of quests that the passed npc will respond to for faction call events.
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addFactionCallId(Collection<Integer> npcIds)
 	{
@@ -2012,8 +2006,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Add this quest to the list of quests that the passed npc will respond to for Character See Events.
-	 * @param npcIds ID of the NPC
+	 * Add this quest to the list of quests that the passed npc will respond to for character see events.
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addAggroRangeEnterId(int... npcIds)
 	{
@@ -2021,8 +2015,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Add this quest to the list of quests that the passed npc will respond to for Character See Events.
-	 * @param npcIds ID of the NPC
+	 * Add this quest to the list of quests that the passed npc will respond to for character see events.
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addAggroRangeEnterId(Collection<Integer> npcIds)
 	{
@@ -2030,7 +2024,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * @param npcIds NPC IDs to register to on see creature event
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addSeeCreatureId(int... npcIds)
 	{
@@ -2038,7 +2032,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * @param npcIds NPC IDs to register to on see creature event
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addSeeCreatureId(Collection<Integer> npcIds)
 	{
@@ -2046,8 +2040,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Register onEnterZone trigger for Zone
-	 * @param zoneId
+	 * Register onEnterZone trigger for zone
+	 * @param zoneId the ID of the zone to register
 	 */
 	public void addEnterZoneId(int zoneId)
 	{
@@ -2059,8 +2053,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Register onEnterZone trigger for Zones
-	 * @param zoneIds
+	 * Register onEnterZone trigger for zones
+	 * @param zoneIds the IDs of the zones to register
 	 */
 	public void addEnterZoneId(int... zoneIds)
 	{
@@ -2071,8 +2065,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Register onEnterZone trigger for Zones
-	 * @param zoneIds
+	 * Register onEnterZone trigger for zones
+	 * @param zoneIds the IDs of the zones to register
 	 */
 	public void addEnterZoneId(Collection<Integer> zoneIds)
 	{
@@ -2083,8 +2077,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Register onExitZone trigger for Zone
-	 * @param zoneId
+	 * Register onExitZone trigger for zone
+	 * @param zoneId the ID of the zone to register
 	 */
 	public void addExitZoneId(int zoneId)
 	{
@@ -2096,8 +2090,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Register onExitZone trigger for Zones
-	 * @param zoneIds
+	 * Register onExitZone trigger for zones
+	 * @param zoneIds the IDs of the zones to register
 	 */
 	public void addExitZoneId(int... zoneIds)
 	{
@@ -2108,8 +2102,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Register onExitZone trigger for Zones
-	 * @param zoneIds
+	 * Register onExitZone trigger for zones
+	 * @param zoneIds the IDs of the zones to register
 	 */
 	public void addExitZoneId(Collection<Integer> zoneIds)
 	{
@@ -2121,7 +2115,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	
 	/**
 	 * Register onEventReceived trigger for NPC
-	 * @param npcIds
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addEventReceivedId(int... npcIds)
 	{
@@ -2130,7 +2124,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	
 	/**
 	 * Register onEventReceived trigger for NPC
-	 * @param npcIds
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addEventReceivedId(Collection<Integer> npcIds)
 	{
@@ -2139,7 +2133,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	
 	/**
 	 * Register onMoveFinished trigger for NPC
-	 * @param npcIds
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addMoveFinishedId(int... npcIds)
 	{
@@ -2148,7 +2142,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	
 	/**
 	 * Register onMoveFinished trigger for NPC
-	 * @param npcIds
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addMoveFinishedId(Collection<Integer> npcIds)
 	{
@@ -2157,7 +2151,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	
 	/**
 	 * Register onNodeArrived trigger for NPC
-	 * @param npcIds ID of NPC to register
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addNodeArrivedId(int... npcIds)
 	{
@@ -2166,7 +2160,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	
 	/**
 	 * Register onNodeArrived trigger for NPC
-	 * @param npcIds ID of NPC to register
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addNodeArrivedId(Collection<Integer> npcIds)
 	{
@@ -2175,7 +2169,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	
 	/**
 	 * Register onRouteFinished trigger for NPC
-	 * @param npcIds ID of NPC to register
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addRouteFinishedId(int... npcIds)
 	{
@@ -2184,7 +2178,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	
 	/**
 	 * Register onRouteFinished trigger for NPC
-	 * @param npcIds ID of NPC to register
+	 * @param npcIds the IDs of the NPCs to register
 	 */
 	public void addRouteFinishedId(Collection<Integer> npcIds)
 	{
@@ -2355,6 +2349,64 @@ public class Quest extends ManagedScript implements IIdentifiable
 		return candidates.get(Rnd.get(candidates.size()));
 	}
 	
+	/**
+	 * Get a random party member from the specified player's party.<br>
+	 * If the player is not in a party, only the player himself is checked.<br>
+	 * The lucky member is chosen by standard loot roll rules -<br>
+	 * each member rolls a random number, the one with the highest roll wins.
+	 * @param player the player whose party to check
+	 * @param npc the NPC used for distance and other checks (if {@link #checkPartyMember(L2PcInstance, L2Npc)} is overriden)
+	 * @return the random party member or {@code null}
+	 */
+	public L2PcInstance getRandomPartyMember(L2PcInstance player, L2Npc npc)
+	{
+		if ((player == null) || !checkDistanceToTarget(player, npc))
+		{
+			return null;
+		}
+		final L2Party party = player.getParty();
+		L2PcInstance luckyPlayer = null;
+		if (party == null)
+		{
+			if (checkPartyMember(player, npc))
+			{
+				luckyPlayer = player;
+			}
+		}
+		else
+		{
+			int highestRoll = 0;
+			
+			for (L2PcInstance member : party.getMembers())
+			{
+				final int rnd = getRandom(1000);
+				
+				if ((rnd > highestRoll) && checkPartyMember(member, npc))
+				{
+					highestRoll = rnd;
+					luckyPlayer = member;
+				}
+			}
+		}
+		if ((luckyPlayer != null) && checkDistanceToTarget(luckyPlayer, npc))
+		{
+			return luckyPlayer;
+		}
+		return null;
+	}
+	
+	/**
+	 * This method is called for every party member in {@link #getRandomPartyMember(L2PcInstance, L2Npc)}.<br>
+	 * It is intended to be overriden by the specific quest implementations.
+	 * @param player the player to check
+	 * @param npc the NPC that was passed to {@link #getRandomPartyMember(L2PcInstance, L2Npc)}
+	 * @return {@code true} if this party member passes the check, {@code false} otherwise
+	 */
+	public boolean checkPartyMember(L2PcInstance player, L2Npc npc)
+	{
+		return true;
+	}
+	
 	/**
 	 * Get a random party member from the player's party who has this quest at the specified quest progress.<br>
 	 * If the player is not in a party, only the player himself is checked.
@@ -2448,9 +2500,9 @@ public class Quest extends ManagedScript implements IIdentifiable
 	
 	/**
 	 * Show an on screen message to the player.
-	 * @param player the player to display the message
-	 * @param text the message
-	 * @param time the display time
+	 * @param player the player to display the message to
+	 * @param text the message to display
+	 * @param time the duration of the message in milliseconds
 	 */
 	public static void showOnScreenMsg(L2PcInstance player, String text, int time)
 	{
@@ -2459,11 +2511,11 @@ public class Quest extends ManagedScript implements IIdentifiable
 	
 	/**
 	 * Show an on screen message to the player.
-	 * @param player the player to display the message
-	 * @param npcString the NPC String to display
-	 * @param position the position in the screen
-	 * @param time the display time
-	 * @param params parameters values to replace in the NPC String
+	 * @param player the player to display the message to
+	 * @param npcString the NPC string to display
+	 * @param position the position of the message on the screen
+	 * @param time the duration of the message in milliseconds
+	 * @param params values of parameters to replace in the NPC String (like S1, C1 etc.)
 	 */
 	public static void showOnScreenMsg(L2PcInstance player, NpcStringId npcString, int position, int time, String... params)
 	{
@@ -2472,11 +2524,11 @@ public class Quest extends ManagedScript implements IIdentifiable
 	
 	/**
 	 * Show an on screen message to the player.
-	 * @param player the player to display the message
-	 * @param systemMsg the System Message to display
-	 * @param position the position in the screen
-	 * @param time the display time
-	 * @param params parameters values to replace in the System Message
+	 * @param player the player to display the message to
+	 * @param systemMsg the system message to display
+	 * @param position the position of the message on the screen
+	 * @param time the duration of the message in milliseconds
+	 * @param params values of parameters to replace in the system message (like S1, C1 etc.)
 	 */
 	public static void showOnScreenMsg(L2PcInstance player, SystemMessageId systemMsg, int position, int time, String... params)
 	{
@@ -3032,7 +3084,7 @@ public class Quest extends ManagedScript implements IIdentifiable
 	 */
 	public static boolean hasQuestItems(L2PcInstance player, int itemId)
 	{
-		return player.getInventory().getItemByItemId(itemId) != null;
+		return (player.getInventory().getItemByItemId(itemId) != null);
 	}
 	
 	/**
@@ -3043,6 +3095,10 @@ public class Quest extends ManagedScript implements IIdentifiable
 	 */
 	public static boolean hasQuestItems(L2PcInstance player, int... itemIds)
 	{
+		if ((itemIds == null) || (itemIds.length == 0))
+		{
+			return false;
+		}
 		final PcInventory inv = player.getInventory();
 		for (int itemId : itemIds)
 		{
@@ -3588,7 +3644,8 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Get a random boolean.
+	 * Get a random boolean.<br>
+	 * Use this method instead of importing {@link com.l2jserver.util.Rnd} utility.
 	 * @return {@code true} or {@code false} randomly
 	 */
 	public static boolean getRandomBoolean()
@@ -3616,12 +3673,12 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Executes a procedure for each player, depending on the parameters.
-	 * @param player the player were the procedure will be executed
-	 * @param npc the related Npc
-	 * @param isSummon {@code true} if the event that call this method was originated by the player's summon
-	 * @param includeParty if {@code true} #actionForEachPlayer(L2PcInstance, L2Npc, boolean) will be called with the player's party members
-	 * @param includeCommandChannel if {@code true} {@link #actionForEachPlayer(L2PcInstance, L2Npc, boolean)} will be called with the player's command channel members
+	 * Execute a procedure for each player depending on the parameters.
+	 * @param player the player on which the procedure will be executed
+	 * @param npc the related NPC
+	 * @param isSummon {@code true} if the event that called this method was originated by the player's summon, {@code false} otherwise
+	 * @param includeParty if {@code true}, #actionForEachPlayer(L2PcInstance, L2Npc, boolean) will be called with the player's party members
+	 * @param includeCommandChannel if {@code true}, {@link #actionForEachPlayer(L2PcInstance, L2Npc, boolean)} will be called with the player's command channel members
 	 * @see #actionForEachPlayer(L2PcInstance, L2Npc, boolean)
 	 */
 	public final void executeForEachPlayer(L2PcInstance player, final L2Npc npc, final boolean isSummon, boolean includeParty, boolean includeCommandChannel)
@@ -3661,9 +3718,9 @@ public class Quest extends ManagedScript implements IIdentifiable
 	
 	/**
 	 * Overridable method called from {@link #executeForEachPlayer(L2PcInstance, L2Npc, boolean, boolean, boolean)}
-	 * @param player the player where the action will be run
-	 * @param npc the Npc related to this action
-	 * @param isSummon {@code true} if the event that call this method was originated by the player's summon
+	 * @param player the player on which the action will be run
+	 * @param npc the NPC related to this action
+	 * @param isSummon {@code true} if the event that called this method was originated by the player's summon
 	 */
 	public void actionForEachPlayer(L2PcInstance player, L2Npc npc, boolean isSummon)
 	{
@@ -3671,9 +3728,9 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Opens the door if presents on the instance and its not open.
-	 * @param doorId
-	 * @param instanceId
+	 * Open a door if it is present on the instance and its not open.
+	 * @param doorId the ID of the door to open
+	 * @param instanceId the ID of the instance the door is in (0 if the door is not not inside an instance)
 	 */
 	public void openDoor(int doorId, int instanceId)
 	{
@@ -3689,9 +3746,9 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Closes the door if presents on the instance and its open
-	 * @param doorId
-	 * @param instanceId
+	 * Close a door if it is present in a specified the instance and its open.
+	 * @param doorId the ID of the door to close
+	 * @param instanceId the ID of the instance the door is in (0 if the door is not not inside an instance)
 	 */
 	public void closeDoor(int doorId, int instanceId)
 	{
@@ -3707,10 +3764,10 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Retriving Door from instances or from the real world.
-	 * @param doorId
-	 * @param instanceId
-	 * @return {@link L2DoorInstance}
+	 * Retrieve a door from an instance or the real world.
+	 * @param doorId the ID of the door to get
+	 * @param instanceId the ID of the instance the door is in (0 if the door is not not inside an instance)
+	 * @return the found door or {@code null} if no door with that ID and instance ID was found
 	 */
 	public L2DoorInstance getDoor(int doorId, int instanceId)
 	{
@@ -3731,10 +3788,10 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Teleport player to/from instance
-	 * @param player
-	 * @param loc
-	 * @param instanceId
+	 * Teleport a player into/out of an instance.
+	 * @param player the player to teleport
+	 * @param loc the {@link Location} object containing the destination coordinates
+	 * @param instanceId the ID of the instance to teleport the player to (0 to teleport out of an instance)
 	 */
 	public void teleportPlayer(L2PcInstance player, Location loc, int instanceId)
 	{
@@ -3742,11 +3799,11 @@ public class Quest extends ManagedScript implements IIdentifiable
 	}
 	
 	/**
-	 * Teleport player to/from instance
-	 * @param player
-	 * @param loc
-	 * @param instanceId
-	 * @param allowRandomOffset
+	 * Teleport a player into/out of an instance.
+	 * @param player the player to teleport
+	 * @param loc the {@link Location} object containing the destination coordinates
+	 * @param instanceId the ID of the instance to teleport the player to (0 to teleport out of an instance)
+	 * @param allowRandomOffset if {@code true}, will randomize the teleport coordinates by +/-Config.MAX_OFFSET_ON_TELEPORT
 	 */
 	public void teleportPlayer(L2PcInstance player, Location loc, int instanceId, boolean allowRandomOffset)
 	{