even more docs

src/engine.h

@@ -44,27 +44,75 @@ class Engine {
 	double delta = 0.0;
 
 	std::unique_ptr<gui::GUI> gui;
+    
+    void updateTimers();
+	void updateHotkeys();
 public:
 	Engine(EngineSettings& settings, EnginePaths* paths);
 	~Engine();
 
-	void updateTimers();
-	void updateHotkeys();
+    /** 
+     * Start main engine input/update/render loop 
+     * Automatically sets MenuScreen
+     */
 	void mainloop();
 
-	Assets* getAssets();
-	gui::GUI* getGUI();
-	EngineSettings& getSettings();
-	void setScreen(std::shared_ptr<Screen> screen);
-	EnginePaths* getPaths();
-	const Content* getContent() const;
-    std::vector<ContentPack>& getContentPacks();
+    /**
+     * Set screen (scene).
+     * nullptr may be used to delete previous screen before creating new one
+     * example:
+     *
+     *     engine->setScreen(nullptr);
+     *     engine->setScreen(std::make_shared<...>(...));
+     * 
+     * not-null value must be set before next frame
+     */
+    void setScreen(std::shared_ptr<Screen> screen);
+    
+    /** 
+     * Change locale to specified
+     * @param locale isolanguage_ISOCOUNTRY (example: en_US)
+     */
 	void setLanguage(std::string locale);
+
+    /** 
+     * Load all selected content-packs and reload assets 
+     */
     void loadContent();
+    /**
+     * Collect world content-packs and load content
+     * @see loadContent
+     * @param folder world folder
+     */
     void loadWorldContent(const fs::path& folder);
+
+    /**
+     * Collect all available content-packs from res/content
+     */
 	void loadAllPacks();
+
+    /** Get current frame delta-time */
     double getDelta() const;
 
+    /** Get active assets storage instance */
+	Assets* getAssets();
+    
+    /** Get main UI controller */
+	gui::GUI* getGUI();
+
+    /** Get writeable engine settings structure instance */
+	EngineSettings& getSettings();
+
+    /** Get engine filesystem paths source */
+	EnginePaths* getPaths();
+
+    /** Get current Content instance */
+	const Content* getContent() const;
+
+    /** Get selected content packs */
+    std::vector<ContentPack>& getContentPacks();
+
+    /** Get current screen */
     std::shared_ptr<Screen> getScreen();
 };
 

src/world/World.h

@@ -33,14 +33,15 @@ class World : Serializable {
     const Content* const content;
     std::vector<ContentPack> packs;
 
-    uint nextInventoryId = 1;
+    int64_t nextInventoryId = 1;
 public:
     WorldFiles* wfile;
 
-    /* Day/night loop timer in range 0..1 
-       0.0 - is midnight
-       0.5 - is noon
-    */
+    /** 
+     * Day/night loop timer in range 0..1 
+     * 0.0 - is midnight
+     * 0.5 - is noon
+     */
     float daytime = timeutil::time_value(10, 00, 00);
     float daytimeSpeed = 1.0f/60.0f/24.0f;
     double totalTime = 0.0;
@@ -53,18 +54,53 @@ public:
           std::vector<ContentPack> packs);
     ~World();
 
+    /** 
+     * Update world day-time and total time
+     * @param delta delta-time
+     */
     void updateTimers(float delta);
+    
+    /**
+     * Write all unsaved level data to the world directory
+     */
     void write(Level* level);
 
-    static ContentLUT* checkIndices(const fs::path& directory,
-                                         const Content* content);
+    /** 
+     * Check world indices and generate ContentLUT if convert required 
+     * @param directory world directory
+     * @param content current Content instance
+     * @return ContentLUT if world convert required else nullptr 
+     */
+    static ContentLUT* checkIndices(const fs::path& directory, const Content* content);
 
+    /**
+     * Create new world
+     * @param name internal world name
+     * @param directory root world directory
+     * @param seed world generation seed
+     * @param settings current engine settings
+     * @param content current engine Content instance 
+     * with all world content-packs applied
+     * @param packs vector of all world content-packs
+     * @return Level instance containing World instance
+     */
     static Level* create(std::string name, 
                          fs::path directory, 
                          uint64_t seed, 
                          EngineSettings& settings, 
                          const Content* content,
                          const std::vector<ContentPack>& packs);
+    
+    /**
+     * Load an existing world
+     * @param directory root world directory 
+     * @param settings current engine settings
+     * @param content current engine Content instance 
+     * with all world content-packs applied
+     * @param packs vector of all world content-packs
+     * @return Level instance containing World instance
+     * @throws world_load_error on world.json load error
+     */
     static Level* load(fs::path directory,
                        EngineSettings& settings,
                        const Content* content,
@@ -73,21 +109,43 @@ public:
     void setName(const std::string& name);
     void setSeed(uint64_t seed);
     
+    /** 
+     * Check if world has content-pack installed 
+     * @param id content-pack id
+     */
     bool hasPack(const std::string& id) const;
-    std::string getName() const;
-    uint64_t getSeed() const;
-    const std::vector<ContentPack>& getPacks() const;
 
-    std::unique_ptr<dynamic::Map> serialize() const override;
-    void deserialize(dynamic::Map *src) override;
+    /**
+     * Get internal world name (not the folder name)
+     * @return name stored in world.json
+     */
+    std::string getName() const;
+
+    /** Get world generation seed */
+    uint64_t getSeed() const;
+
+    /**
+     * Get vector of all content-packs installed in world
+     */
+    const std::vector<ContentPack>& getPacks() const;
     
-    uint getNextInventoryId() {
+    /**
+     * Get next inventory id and increment it's counter
+     * @return integer >= 1
+    */
+    int64_t getNextInventoryId() {
         return nextInventoryId++;
     }
 
+    /**
+     * Get current world Content instance
+     */
     const Content* getContent() const {
         return content;
     }
+
+    std::unique_ptr<dynamic::Map> serialize() const override;
+    void deserialize(dynamic::Map *src) override;
 };
 
 #endif /* WORLD_WORLD_H_ */