(svn r18562) -Document: improve clarity of the AIAccounting class

src/ai/api/ai_accounting.hpp

@@ -18,12 +18,14 @@
  * Class that keeps track of the costs, so you can request how much a block of
  *  commands did cost in total. Works in both Execute as in Test mode.
  * Example:
+ * <pre>
  *   {
  *     local costs = AIAccounting();
  *     BuildRoad(from_here, to_here);
  *     BuildRoad(from_there, to_there);
  *     print("Costs for route is: " + costs.GetCosts());
  *   }
+ * </pre>
  */
 class AIAccounting : public AIObject {
 public:
@@ -31,26 +33,30 @@ public:
 
 	/**
 	 * Creating instance of this class starts counting the costs of commands
-	 *   from zero.
+	 *   from zero. Saves the current value of GetCosts so we can return to
-	 * @note when the instance is destroyed, he restores the costs that was
+	 *   the old value when the instance gets deleted.
-	 *   current when the instance was created!
 	 */
 	AIAccounting();
 
 	/**
-	 * Destroying this instance reset the costs to the value it was
+	 * Restore the AIAccounting that was on top when we created this instance.
-	 *   in when the instance was created.
+	 *   So basically restore the value of GetCosts to what it was before we
+	 *   created this instance.
 	 */
 	~AIAccounting();
 
 	/**
 	 * Get the current value of the costs.
 	 * @return The current costs.
+	 * @note when nesting AIAccounting instances all instances' GetCosts
+	 *   will always return the value of the 'top' instance.
 	 */
 	Money GetCosts();
 
 	/**
 	 * Reset the costs to zero.
+	 * @note when nesting AIAccounting instances all instances' ResetCosts
+	 *   will always effect on the 'top' instance.
 	 */
 	void ResetCosts();