Added the documentation

For now it's very basic.

doc/README.md

@@ -0,0 +1,8 @@
+# Documentation
+There are two types of documentation in this folder.
+User documentation and developer documentation.
+
+The [User documentation](user_doc.md) is about how the features work.
+
+The [Developer documentation](developer_doc.md) is related to the
+code design of the application.

doc/developer_doc.md

@@ -0,0 +1,84 @@
+# Developer documentation
+This page is about the code design of the
+game, the purpose of the various components
+and the interaction between them.
+
+## Entry point, init and destroy functions
+The initial functions are in the file `entry_point.c`.
+The main function is `matagotchi_app()`.
+
+The init function is `context_alloc()` and the
+corresponding destroy function is `context_free()`.
+`context_alloc()` init the data structures and
+the GUI, through the function `init_gui()`.
+
+## Threads
+There are 3 threads in the application.
+The starting functions for them are in `threads.c`.
+
+### Main thread
+It is the same thread that starts when entering
+the application.
+Once the init is completed it is confined in the
+function `main_thread()`. The purpose is to start
+and stop the secondary thread. It starts it, then
+blocks waiting the UI thread to end and once finished
+notifies the secondary thread to stop.
+
+### Secondary thread
+This thread is started by the main thread. Its
+purpose is to perform background operations and to
+process user inputs. The main function for
+this thread is `secondary_thread()`.
+
+It receives messages from the other two threads.
+The main thread sends shutdown requests. The
+UI thread sends actions to be performed because
+the user selected something on the UI.
+
+If no message is received, this thread performs
+background operations.
+
+### UI thread
+This is the thread where the UI lives.
+It is started by the function call
+`start_gui_and_block()` in the main thread.
+It ends when the user tries to go back from
+the main screen. When the back button is pressed,
+the view dispatcher is stopped with the function
+call `view_dispatcher_stop()` in the file
+`src/scene/main_scene.c`.
+
+When the view dispatcher stops, the
+`start_gui_and_block()` function returns, freeing
+the main thread.
+
+## Game parameters
+The game can be tuned by changing some configurations.
+It is possile to modify the speed of the events,
+the frequency and the probability of all the
+game features.
+
+All configurations are in the file `constants.h`.
+
+## GUI
+The application makes use of `view_dispatcher`,
+`scene_manager` and `modules`.
+
+The `view_dispatcher` is responsible for the low
+level APIs. It handles the user inputs and pass them
+to the high level APIs such as the modules.
+
+For every visible screen, the `view_dispatcher` registers
+the `module` element to show.
+
+The `module` is a screen with some predefined graphical
+elements.
+
+The `scene_manager` is a collection of callback functions
+that can be loaded or unloaded to pass from a scene
+to another one. This could be done manually with the
+`view_dispatcher` APIs, but it's easier to associate to
+each screen a set of callbacks to use and ask the
+`scene_manager` to swap the when moving from one screen
+to another.

doc/user_doc.md

@@ -0,0 +1,52 @@
+# User documentation
+This page describes how to interact with the game
+and how the state progresses.
+
+## Settings
+In the settings menu it's possible to re-initialize
+the game. All progresses will be lost.
+
+From the settings it is also possible to access the
+"about" screen.
+
+## Features
+### Experience
+The Experience (XP) increases periodically. It
+represents the evolution of the pet and it brings
+him from the Egg stage until the Adult stage and
+ending with the death due to the old age.
+
+Every stage has a maximum amount of XP that are
+required to pass to the next stage. The egg only
+has 1XP, because the only goal for this stage
+is to start the game.
+
+The pet may get a new XP every few minutes.
+The probability to get it it's not 100%, so
+it may require multiple cycles to get one.
+
+### Hunger
+The Hunger (HU) is the indication of how
+well fed is the pet. 100/100 means he's full, 0/100
+means he's very hungry.
+
+You can feed the pet by giving him a candy. Each
+candy restores a variable number of HU. Once the
+pet is full, he won't accept candies anymore.
+
+When the HU indicator goes to 0, the pet will start
+loosing health (see below).
+
+### Health
+The Health (HP) indicator represents the health of the
+pet in a scale from 0 to 100. 100 means healthy and 0
+means dying.
+
+The pet can lose HP in two ways: for starvation, when the
+HU indicator is 0, or a cause of an illness.
+
+The health is checked periodically. It will for sure lose
+1HP at every check if the HU indicator is 0, while it's
+random whether 1XP is lost for an illness.
+
+You can restore the health by giving the pet a medicine.