From: ShadowNinja <shadowninja@minetest.net>
Date: Fri, 30 Oct 2015 05:25:44 +0000 (-0400)
Subject: Add basic AreaStore method documentation
X-Git-Tag: 0.4.14~187
X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=8ae1e1f4d29342d5d95648f7be1c8fe7f36eda52;p=oweals%2Fminetest.git

Add basic AreaStore method documentation
---

diff --git a/src/util/areastore.h b/src/util/areastore.h
index 20e9bdfc5..5b4e9a71f 100644
--- a/src/util/areastore.h
+++ b/src/util/areastore.h
@@ -67,21 +67,36 @@ public:
 	virtual void reserve(size_t count) {};
 	size_t size() const { return areas_map.size(); }
 
-	// Updates the area's ID
+	/// Add an area to the store.
+	/// Updates the area's ID.
 	virtual bool insertArea(Area *a) = 0;
+
+	/// Removes an area from the store by ID.
+	/// @return Whether the area was in the store and removed.
 	virtual bool removeArea(u32 id) = 0;
+
+	/// Finds areas that the passed position is contained in.
+	/// Stores output in passed vector.
 	void getAreasForPos(std::vector<Area *> *result, v3s16 pos);
+
+	/// Finds areas that are completely contained inside the area defined
+	/// by the passed edges.  If @p accept_overlap is true this finds any
+	/// areas that intersect with the passed area at any point.
 	virtual void getAreasInArea(std::vector<Area *> *result,
 		v3s16 minedge, v3s16 maxedge, bool accept_overlap) = 0;
+
+	/// Sets cache parameters.
 	void setCacheParams(bool enabled, u8 block_radius, size_t limit);
 
+	/// Returns a pointer to the area coresponding to the passed ID,
+	/// or NULL if it doesn't exist.
 	const Area *getArea(u32 id) const;
 
 #if 0
 	typedef bool (*ForEachCallback)(const Area *a, void *arg);
-	// Calls a passed function for every stored area, until the
-	// callback returns true.  If that happens, it returns true,
-	// if the search is exhausted, it returns false.
+	/// Calls a passed function for every stored area, until the
+	/// callback returns true.  If that happens, it returns true,
+	/// if the search is exhausted, it returns false.
 	virtual bool forEach(ForEachCallback, void *arg=NULL) const = 0;
 
 	void serialize(std::ostream &is) const;
@@ -89,8 +104,15 @@ public:
 #endif
 
 protected:
+	/// Invalidates the getAreasForPos cache.
+	/// Call after adding or removing an area.
 	void invalidateCache();
+
+	/// Implementation of getAreasForPos.
+	/// getAreasForPos calls this if the cache is disabled.
 	virtual void getAreasForPosImpl(std::vector<Area *> *result, v3s16 pos) = 0;
+
+	/// Returns the next area ID and increments it.
 	u32 getNextId() { return m_next_id++; }
 
 	// Note: This can't be an unordered_map, since all
@@ -99,10 +121,13 @@ protected:
 	AreaMap areas_map;
 
 private:
+	/// Called by the cache when a value isn't found in the cache.
 	static void cacheMiss(void *data, const v3s16 &mpos, std::vector<Area *> *dest);
 
 	bool m_cache_enabled;
-	u8 m_cacheblock_radius; // if you modify this, call invalidateCache()
+	/// Range, in nodes, of the getAreasForPos cache.
+	/// If you modify this, call invalidateCache()
+	u8 m_cacheblock_radius;
 	LRUCache<v3s16, std::vector<Area *> > m_res_cache;
 
 	u32 m_next_id;