Merge pull request #39 from radonthetyrant/master

improved documentation in HelloWorldExample/src/entry_point.cpp

examples/HelloWorld/src/entry_point.cpp

@@ -1,8 +1,8 @@
 /**
-Attention!
-This file has Oxygine initialization stuff.
-If you just started you don't need to understand it exactly you could check it later.
-You could start from example.cpp and example.h it has main functions being called from there
+	Attention!
+	This file initializes the Oxygine engine.
+	If you just started here and don't understand the code completely, feel free to come back later.
+	You can start from example.cpp and example.h, which main functions are called from here.
 */
 #include "core/oxygine.h"
 #include "Stage.h"
@@ -14,46 +14,48 @@ You could start from example.cpp and example.h it has main functions being calle
 using namespace oxygine;
 
 
-//called each frame
+// This function is called each frame
 int mainloop()
 {
+	// It gets passed to our example game implementation
     example_update();
-    //update our stage
-    //update all actors. Actor::update would be called also for all children
+
+    // Update our stage
+    // Update all actors. Actor::update will also be called for all its children
     getStage()->update();
 
     if (core::beginRendering())
     {
         Color clearColor(32, 32, 32, 255);
         Rect viewport(Point(0, 0), core::getDisplaySize());
-        //render all actors. Actor::render would be called also for all children
+        // Render all actors inside the stage. Actor::render will also be called for all its children
         getStage()->render(clearColor, viewport);
 
         core::swapDisplayBuffers();
     }
 
-    //update internal components
-    //all input events would be passed to Stage::instance.handleEvent
-    //if done is true then User requests quit from app.
+	// Update engine-internal components
+	// If input events are available, they are passed to Stage::instance.handleEvent
+	// If the function returns true, it means that the user requested the application to terminate
     bool done = core::update();
 
     return done ? 1 : 0;
 }
 
-//it is application entry point
+// Application entry point
 void run()
 {
     ObjectBase::__startTracingLeaks();
 
-    //initialize Oxygine's internal stuff
+    // Initialize Oxygine's internal stuff
     core::init_desc desc;
     desc.title = "Oxygine Application";
 
 #if OXYGINE_SDL || OXYGINE_EMSCRIPTEN
-    //we could setup initial window size on SDL builds
+	// The initial window size can be set up here on SDL builds
     desc.w = 960;
     desc.h = 640;
-    //marmalade settings could be changed from emulator's menu
+    // Marmalade settings can be modified from the emulator's menu
 #endif
 
 
@@ -61,59 +63,59 @@ void run()
     core::init(&desc);
 
 
-    //create Stage. Stage is a root node
+    // Create the stage. Stage is a root node for all updateable and drawable objects
     Stage::instance = new Stage(true);
     Point size = core::getDisplaySize();
     getStage()->setSize(size);
 
-    //DebugActor is a helper actor node. It shows FPS, memory usage and other useful stuff
+    // DebugActor is a helper actor node. It shows FPS, memory usage and other useful stuff
     DebugActor::show();
 
-    //initialize this example stuff. see example.cpp
+	// Initializes our example game. See example.cpp
     example_init();
 
 #ifdef EMSCRIPTEN
     /*
-    if you build for Emscripten mainloop would be called automatically outside.
-    see emscripten_set_main_loop below
+    If you build for Emscripten, mainloop is called automatically and shouldn't be called here.
+    See emscripten_set_main_loop in the EMSCRIPTEN section below
     */
     return;
 #endif
 
 
-    //here is main game loop
+    // This is the main game loop.
     while (1)
     {
         int done = mainloop();
         if (done)
             break;
     }
-    //user wants to leave application...
+    // If we get here, the user has requested the Application to terminate.
 
-    //lets dump all created objects into log
-    //all created and not freed resources would be displayed
+    // We dump and log all our created objects that have not been freed yet
     ObjectBase::dumpCreatedObjects();
 
-    //lets cleanup everything right now and call ObjectBase::dumpObjects() again
-    //we need to free all allocated resources and delete all created actors
-    //all actors/sprites are smart pointer objects and actually you don't need it remove them by hands
-    //but now we want delete it by hands
+	/*
+	Let's clean up everything right now and call ObjectBase::dumpObjects() again.
+	We need to free all allocated resources and delete all created actors.
+	All actors/sprites are smart-pointer objects and don't need to be removed by hand.
+	But now we want to delete it by hand.
+	*/
 
-    //check example.cpp
+    // See example.cpp for the shutdown function implementation
     example_destroy();
 
-
     //renderer.cleanup();
 
-    /**releases all internal components and Stage*/
+    // Releases all internal components and the stage
     core::release();
 
-    //dump list should be empty now
-    //we deleted everything and could be sure that there aren't any memory leaks
+    // The dump list should be empty by now,
+    // we want to make sure that there aren't any memory leaks, so we call it again.
     ObjectBase::dumpCreatedObjects();
 
     ObjectBase::__stopTracingLeaks();
-    //end
+    // end
 }
 
 #ifdef __S3E__