update the documentation for the new structure

CONTRIBUTING.md

@@ -14,11 +14,11 @@ You may also open issues on [GitHub][] or contact me directly by mail.
 Documentation
 -------------
 
-To generate the technical documentation of the game with Doxygen, you need to
-cd to the `docs/` directory and run `make apidoc`. The documentation will be
-accessible from `docs/html/index.html`. By the way, if you didn't have Doxygen
-installed when you ran `./configure`, you'll need to call it again for it to
-detect Doxygen.
+The HTML documentation is generated by Doxygen. Run `make html` and open
+`html/index.html` relative to your build directory to browse it.
+
+Doxygen is detected by CMake when you configure the project. You may need to
+re-run CMake if it didn't detect Doxygen after you installed it.
 
 
 Technical choices

README.md

@@ -140,4 +140,4 @@ Documentation
 The user manual's man page is installed in the standard man directory, but you
 may view it directly from `share/man/`.
 
-For the technical documentation, please look at `CONTRIBUTING.md`.
+For the technical documentation, please look at CONTRIBUTING.md.

index.md

@@ -22,72 +22,29 @@ time, some textures are drawn on-the-fly when required, sometimes causing a
 frame to be dropped. The frame rate is fixed at 60 FPS.
 
 
-Code structure
---------------
-
-\dot
-digraph modules {
-	rankdir=BT;
-	node [shape=rect];
-	Beatmap;
-	subgraph {
-		rank=same;
-		Audio;
-		UI -> Graphics;
-	}
-	Audio -> Beatmap;
-	Graphics -> Beatmap;
-	UI -> Beatmap;
-	Game -> Audio;
-	Game -> Graphics;
-	Game -> Beatmap;
-	Game -> UI;
-	Osu -> Game;
-	Main -> Osu;
-}
-\enddot
-
-The \ref core module provides generic modules used about everywhere in the
-code. It's an implicit dependency of all the modules.
-
-The \ref beatmap module handles the complete loading and parsing of the beatmap
-files. It is self-contained. In particular, it is not going to load anything
-audio or graphical. Since the beatmap is central to the game, most modules
-depend on it for one of the structure it defines.
-
-The \ref audio module handles everything audio-related from audio file loading
-down to the actual output to the sound device.
-
-The \ref graphics module handles the window creation and provides accelerated
-drawing primitives. It is not directly related to the game, but uses the
-geometric types defined by the beatmap module.
-
-The \ref ui module provides user interface elements as widgets. Widgets are the
-basic block for a composable user interface.
-
-The \ref game module joins every module together and runs the main event loop
-of the game. It watches the audio and the user's keyboard and mouse events to
-manipulate the beatmap state, then schedules the drawing of the window. It is
-agnostic to the game mode.
-
-The \ref osu module implements the osu!standard game mode as an extension of
-the \ref game module.
-
-The *main* module \ref src/oshu/main.cc is the entry-point of oshu! and provides a
-command-line interface to briefly configure the game, and then yields control
-to the game module.
-
-
-Error handling
---------------
-
-Unless mentioned otherwise, the oshu functions that may fail return an int
-which is either 0 on success, and a negative value on error. That negative
-value will be -1 most of the time.
-
-Error messages are logged with \ref oshu_log_error by the *callee*. This makes
-the code clearer for the caller, and the callee has much more details about the
-error than the caller.
-
-With C++, more and more functions will starting exceptions rather than handling
-errors manually.
+Directory structure
+-------------------
+
+The repository is organized into the usual directory structure, if you're
+familiar with the FHS.
+
+```
+include/
+	Public .h headers files for liboshu.
+	They contain most of the Doxygen documentation, and define the
+	cross-module interfaces.
+lib/
+	Implementation of liboshu.
+	It may also contain private header files.
+src/
+	Source of the executables.
+	Most of them are light wrappers around liboshu, providing a CLI
+	interface.
+share/
+	Resources and other static assets.
+	Includes audio samples and man pages.
+test/
+	The test suite, ensuring liboshu and the executables work well.
+```
+
+\ref liboshu accounts for the biggest part of the project.

lib/index.md

@@ -0,0 +1,58 @@
+liboshu {#liboshu}
+=======
+
+Modules
+-------
+
+liboshu is organized into various interconnected modules. For maximum clarity,
+it is important the modules are not circularly linked to each other, and that
+the responsibility of every module is clearly defined.
+
+Below is the dependency graph of the modules:
+
+\dot
+digraph modules {
+	rankdir=BT;
+	node [shape=rect];
+	Beatmap;
+	subgraph {
+		rank=same;
+		Audio;
+		UI -> Graphics;
+	}
+	Audio -> Beatmap;
+	Graphics -> Beatmap;
+	UI -> Beatmap;
+	Game -> Audio;
+	Game -> Graphics;
+	Game -> Beatmap;
+	Game -> UI;
+	Osu -> Game;
+}
+\enddot
+
+The \ref core module provides generic modules used about everywhere in the
+code. It's an implicit dependency of all the modules.
+
+The \ref beatmap module handles the complete loading and parsing of the beatmap
+files. It is self-contained. In particular, it is not going to load anything
+audio or graphical. Since the beatmap is central to the game, most modules
+depend on it for one of the structure it defines.
+
+The \ref audio module handles everything audio-related from audio file loading
+down to the actual output to the sound device.
+
+The \ref graphics module handles the window creation and provides accelerated
+drawing primitives. It is not directly related to the game, but uses the
+geometric types defined by the beatmap module.
+
+The \ref ui module provides user interface elements as widgets. Widgets are the
+basic block for a composable user interface.
+
+The \ref game module joins every module together and runs the main event loop
+of the game. It watches the audio and the user's keyboard and mouse events to
+manipulate the beatmap state, then schedules the drawing of the window. It is
+agnostic to the game mode.
+
+The \ref osu module implements the osu!standard game mode as an extension of
+the \ref game module.