Add basic AreaStore method documentation

diff --git a/src/util/areastore.h b/src/util/areastore.h
index 20e9bdfc52ecfcafc54103a1273a5af322abe44b..5b4e9a71f31ee31533ce4a35c9f9282800036418 100644 (file)
--- 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;