Initial commit

mainpage.h

@@ -0,0 +1,101 @@
+/**
+* @mainpage
+* @section intro Introduction
+* The console version of the popular 'Mine Sweeper' game.
+*
+* The board consists of initially covered cells. Some of these cells carries mines. 
+*
+* Cells can be marked as having a mine (mine detected) or as being suspected of carrying a mine (mine suspected).
+*
+* Cells can be uncovered to reveal their content.
+* Cells may show a number after they are uncovered. This number tells how many of their eight direct neighbor cells 
+* carries a mine and are therefore 'dangerous neighbors'. If a cell without dangerous neighbors is uncovered,
+* all neighbor cells of that cell are uncovered as well. If such a neighbor cell again has no dangerous neighbors,
+* all neighbor cells of this cell are uncovered also, and so on.
+* 
+* The objective of the game is find all cells carrying a mine without uncovering those. The game is won,
+* if each cell carrying a mine is marked as such (mine detected) AND all other cells are uncovered.
+* If a cell that carries a mine is uncovered, the game is last as the mine detonates.
+*
+* Cells are addressed by their column and row coordinate. Before any action can be taken on a cell, it
+* need to be selected first. Afterwards actions such as setting or clearing markers as well as uncovering
+* the cell can be performed. Alternatively a different cell can be selected. This approach shall avoid 
+* performing an action on a 'wrong' cell.
+* 
+* @section objective Assignment Objective
+* In this assignment the required Abstract Data Types and the game logic as well as user interface interaction 
+* shall be implemented. A visualizer for the complete game is provided and shall be used. The visualizer is also
+* capable of capturing user inputs and provides the captured result.
+*
+* The 'main loop' of the application shall be implemented in `ms_main_driver.c`, function `ui_branch`. 
+*
+* That main loop shall:
+* #Start a game
+* #visualize the initial game using `ms_visualizer`
+* #evaluate the user input provided after `ms_visualize()` returns
+* #perform the desired action, e.g. selecting a cell, set a marker, or quit the game
+* #continue with step 2 until the captured action is 'quit' or the game is over (solved or failed)
+*
+* The minimal main loop described above may be extended (surrounded) by an outer loop, which allows to 
+* restart a game in a different mode.
+*
+* Note that `ms_visualizer` supported a 'cheat' mode, which shows the content of covered cells. This may
+* be helpful during development.
+*
+* 
+* **Configuration**
+*
+* Because we operate on static memory, the maximum size of the board in each dimension can be configured in `config.h`.
+* 
+* **Setup and Execution**
+*
+* Initially the board has the set number of cells, all cells are covered. No cell carries a mine at this point in time.
+* After the user uncovers the first cell, the mines are distributes and the number of dangerous neighbors is calculated.
+* The first uncovered cell shall be empty (and therefore uncover neighbor cells, as described above) for sure, to 
+* avoid ambiguous configuration on the first action.
+*
+* **Visualization**
+
+* As described above, the visualization library realized by `ms_visualizer` is capable to render the complete game, including
+* status bar and user prompts as well as capturing user input. User interface related texts and symbols can be more or less 
+* freely defined in `ms_ui_utils.c`. The visualizer does not make assumptions on marker presentation or input keys.
+*
+* @section assignment Assignment
+* This is a rather complex assignment, therefore it is vital, to develop the code in a focused and clean way, step by step.
+* Many unit tests are provided to ease development. Some unit tests provide also helpful debugging traces. If too many 
+* failed unit tests appear - especially at the beginning of development- they can be commented in file `ms_test_driver.c`
+* for files that are currently not in focus. However, they need to be reactivated as development proceeds.
+* 
+* Hint: Read and obey the comment within the code.
+*
+* -# Complete 
+*   - include guards
+*   - forward declarations, 
+*   - types, 
+*   - and function for ADTs in `ms_general.h`, `ms_cell.h`, `ms_board.c`, `ms_game.h`, and `ms_ui_utils.h`.
+*   .
+*   - Types in template files may be marked as `<type>` within header and source files or may be omitted completely. Replace `<type>`
+*     with the correct type and complete missing types. Some types, those which are shared among multiple sources, are located in `general.h`.
+*   - Parameter lists of function in a template files may be missing or incomplete.
+* -# Make the program and tests compile: Implement all functions in all relevant files declared in the headers 
+*    EMTPY (return nothing, 0, false, ... as required).
+*   - All unit tests shall run but FAIL after this step
+*   - **--COMMIT--**
+* -# Implement the empty functions one by one to make the unit tests pass one by one.
+*   - Proposed order: ms_ui_utils, ms_cell, ms_board, ms_game.
+*   - The purpose of a function is specified as API documentation within the header files.
+*   - Obey comments in source files. Run the unit tests frequently and fix failures.
+*   - **--COMMIT-- after each implemented function.**
+* -# Implement the main loop and other missing parts in `main_driver.c` functions.
+*   - **--COMMIT--**
+* -# Run the game and enjoy
+*
+* @section notes Notes
+* -# make cleantest: This new make target for clearing the console, building, and running unit test is available.
+* -# The unit test for solving the game `test_msg_get_state__success` fails in rare cases even if the implementation is corret.
+* -# Visualization is implemented for Linux shell, it will not work on Windows.
+* -# Sometimes changes are not properly detected by incremental builds. If something very strange 
+*    happens during compilation, try to run `make clean` followed by `make` to start a clean build.
+*    This approach is also recommended after everthing is done, because some compiler warning appears
+*    only in clean builds. 
+*/