add documentation to LLAgent::addRegionChangedCallback and improve logging

2 files changed, 21 insertions, 4 deletions

diff --git a/indra/newview/llagent.cpp b/indra/newview/llagent.cpp
index da29aaff50..5302ae2636 100755
--- a/indra/newview/llagent.cpp
+++ b/indra/newview/llagent.cpp
@@ -261,9 +261,7 @@ bool handleSlowMotionAnimation(const LLSD& newvalue)
 
 void LLAgent::setCanEditParcel() // called via mParcelChangedSignal
 {
-	LL_DEBUGS("AgentLocation") << LL_ENDL;
 	bool can_edit = LLToolMgr::getInstance()->canEdit();
-
 	gAgent.mCanEditParcel = can_edit;
 }
 
@@ -837,7 +835,7 @@ void LLAgent::handleServerBakeRegionTransition(const LLUUID& region_id)
 
 void LLAgent::changeParcels()
 {
-	LL_DEBUGS("AgentLocation") << LL_ENDL;
+	LL_DEBUGS("AgentLocation") << "Calling ParcelChanged callbacks" << LL_ENDL;
 	// Notify anything that wants to know about parcel changes
 	mParcelChangedSignal();
 }
@@ -920,6 +918,8 @@ void LLAgent::setRegion(LLViewerRegion *regionp)
 	}
 	mRegionp = regionp;
 
+	// TODO - most of what follows probably should be moved into callbacks
+
 	// Pass the region host to LLUrlEntryParcel to resolve parcel name
 	// with a server request.
 	LLUrlEntryParcel::setRegionHost(getRegionHost());
diff --git a/indra/newview/llagent.h b/indra/newview/llagent.h
index fafa166efd..0662be897a 100755
--- a/indra/newview/llagent.h
+++ b/indra/newview/llagent.h
@@ -253,7 +253,24 @@ private:
 	LLHost			getRegionHost() const;
 	BOOL			inPrelude();
 
-	// Register a boost callback to be called when the agent changes regions
+	/**
+	 * Register a boost callback to be called when the agent changes regions
+	 * Note that if you need to access a capability for the region, you may need to wait
+	 * for the capabilities to be received, since in some cases your region changed
+	 * callback will be called before the capabilities have been received.  Your callback
+	 * may need to look something like:
+	 *
+	 * 	 LLViewerRegion* region = gAgent.getRegion();
+	 * 	 if (region->capabilitiesReceived())
+	 * 	 {
+	 *       useCapability(region);
+	 * 	 }
+	 * 	 else // Need to handle via callback after caps arrive.
+	 * 	 {
+	 *       region->setCapabilitiesReceivedCallback(boost::bind(&useCapability,region,_1));
+	 *       // you may or may not want to remove that callback
+	 * 	 }
+	 */
 	typedef boost::function<void()> region_changed_callback_t;
 	boost::signals2::connection     addRegionChangedCallback(region_changed_callback_t);