2 files changed, 25 insertions, 5 deletions

diff --git a/src/Mobs/PassiveMonster.cpp b/src/Mobs/PassiveMonster.cpp
index e39f6e23d..b700c0c5d 100644
--- a/src/Mobs/PassiveMonster.cpp
+++ b/src/Mobs/PassiveMonster.cpp
@@ -77,17 +77,20 @@ void cPassiveMonster::Tick(std::chrono::milliseconds a_Dt, cChunk & a_Chunk)
 	{
 		m_LovePartner = nullptr;
 	}
+
+	// if we have a partner, mate
 	if (m_LovePartner != nullptr)
 	{
-		// if we have a partner, bump into them until baby is made
+
 		if (m_MatingTimer > 0)
 		{
+			// If we should still mate, keep bumping into them until baby is made
 			Vector3d Pos = m_LovePartner->GetPosition();
 			MoveToPosition(Pos);
 		}
 		else
 		{
-			// spawn baby
+			// Mating finished. Spawn baby
 			Vector3f Pos = (GetPosition() + m_LovePartner->GetPosition()) * 0.5;
 			m_World->SpawnMob(Pos.x, Pos.y, Pos.z, GetMobType(), true);
 
@@ -100,6 +103,7 @@ void cPassiveMonster::Tick(std::chrono::milliseconds a_Dt, cChunk & a_Chunk)
 	}
 	else
 	{
+		// We have no partner, so we just chase the player if they have our breeding item
 		cItems FollowedItems;
 		GetFollowedItems(FollowedItems);
 		if (FollowedItems.Size() > 0)
@@ -117,6 +121,7 @@ void cPassiveMonster::Tick(std::chrono::milliseconds a_Dt, cChunk & a_Chunk)
 		}
 	}
 
+	// If we are in love mode but we have no partner, search for a partner neabry
 	if (m_LoveTimer > 0)
 	{
 		if (m_LovePartner == nullptr)
@@ -133,7 +138,7 @@ void cPassiveMonster::Tick(std::chrono::milliseconds a_Dt, cChunk & a_Chunk)
 
 				virtual bool Item(cEntity * a_Entity) override
 				{
-					// if we're the same species as someone around and they dont have a partner, swipe right
+					// if we're the same species as someone around and they don't have a partner, start mating with them
 					if ((a_Entity->GetEntityType() == m_Me->GetEntityType()) && (a_Entity != m_Me))
 					{
 						cPassiveMonster * Me = static_cast<cPassiveMonster*>(m_Me);
@@ -172,7 +177,7 @@ void cPassiveMonster::OnRightClicked(cPlayer & a_Player)
 {
 	super::OnRightClicked(a_Player);
 
-	// if right clicked on the player with breeding items, go into lovemode
+	// If a player holding breeding items right-clicked me, go into love mode
 	if ((m_LoveCooldown == 0) && !IsInLove() && !IsBaby())
 	{
 		short HeldItem = a_Player.GetEquippedItem().m_ItemType;
diff --git a/src/Mobs/PassiveMonster.h b/src/Mobs/PassiveMonster.h
index ecce4ceb6..0e9250e6c 100644
--- a/src/Mobs/PassiveMonster.h
+++ b/src/Mobs/PassiveMonster.h
@@ -11,7 +11,7 @@ class cPassiveMonster :
 	public cMonster
 {
 	typedef cMonster super;
-	
+
 public:
 	cPassiveMonster(const AString & a_ConfigName, eMonsterType a_MobType, const AString & a_SoundHurt, const AString & a_SoundDeath, double a_Width, double a_Height);
 
@@ -27,17 +27,32 @@ public:
 	/** Returns the items that make the animal breed - this is usually the same as the ones that make the animal follow, but not necessarily. */
 	virtual void GetBreedingItems(cItems & a_Items) { GetFollowedItems(a_Items); }
 
+	/** Returns the partner which the monster is currently mating with. */
 	cPassiveMonster * GetPartner(void) const { return m_LovePartner; }
+
+	/** Start the mating process. Causes the monster to keep bumping into the partner until m_MatingTimer reaches zero. */
 	void EngageLoveMode(cPassiveMonster * a_Partner);
+
+	/** Finish the mating process. Called after a baby is born. Resets all breeding related timers and sets m_LoveCooldown to 20 minutes. */
 	void ResetLoveMode();
 
+	/** Returns whether the monster has just been fed and is ready to mate. If this is "true" and GetPartner isn't "nullptr", then the monster is mating. */
 	bool IsInLove() const { return (m_LoveTimer > 0); }
+
+	/** Returns whether the monster is tired of breeding and is in the cooldown state. */
 	bool IsInLoveCooldown() const { return (m_LoveCooldown > 0); }
 
 protected:
+	/** The monster's breeding partner. */
 	cPassiveMonster * m_LovePartner;
+
+	/** If above 0, the monster is in love mode, and will breed if a nearby monster is also in love mode. Decrements by 1 per tick till reaching zero. */
 	int m_LoveTimer;
+
+	/** If above 0, the monster is in cooldown mode and will refuse to breed. Decrements by 1 per tick till reaching zero. */
 	int m_LoveCooldown;
+
+	/** The monster is engaged in mating, once this reaches zero, a baby will be born. Decrements by 1 per tick till reaching zero, then a baby is made and ResetLoveMode() is called. */
 	int m_MatingTimer;
 };