From 5921465c7047a1435a5f49460b3f8bfff2b591f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Mangano-Tarumi?= Date: Sat, 3 Mar 2018 14:13:25 +0100 Subject: [PATCH] update the documentation for the new structure --- CONTRIBUTING.md | 10 +++--- README.md | 2 +- index.md | 95 ++++++++++++++----------------------------------- lib/index.md | 58 ++++++++++++++++++++++++++++++ 4 files changed, 90 insertions(+), 75 deletions(-) create mode 100644 lib/index.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a15640a..3da770e 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/README.md b/README.md index 8ec73c9..baa1b40 100644 --- a/README.md +++ b/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. diff --git a/index.md b/index.md index 3f288ce..15a8551 100644 --- a/index.md +++ b/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. diff --git a/lib/index.md b/lib/index.md new file mode 100644 index 0000000..726c18b --- /dev/null +++ b/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.