Add basic AreaStore method documentation

minetest · Mar 7, 2016 · 8ae1e1f · 8ae1e1f
1 parent 6e9d713
commit 8ae1e1f
Showing 1 changed file with 30 additions and 5 deletions.
diff --git a/src/util/areastore.h b/src/util/areastore.h
@@ -67,30 +67,52 @@ class AreaStore {
 	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;
 	bool deserialize(std::istream &is);
 #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 @@ class AreaStore {
 	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;