dogo · Sep 14, 2026 · Sep 14, 2026 · Sep 14, 2026
diff --git a/Doxyfile b/Doxyfile
@@ -48,7 +48,7 @@ PROJECT_NAME           = "OldSchool Library"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         =
+PROJECT_NUMBER         = $(OSL_VERSION)
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -190,7 +190,7 @@ FULL_PATH_NAMES        = YES
 # will be relative from the directory where Doxygen is started.
 # This tag requires that the tag FULL_PATH_NAMES is set to YES.
 
-STRIP_FROM_PATH        = "C:/Documents and Settings/Florian/"
+STRIP_FROM_PATH        = .
 
 # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
 # path mentioned in the documentation of a class, which tells the reader which
@@ -1896,7 +1896,7 @@ MATHJAX_CODEFILE       =
 # The default value is: YES.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-SEARCHENGINE           = NO
+SEARCHENGINE           = YES
 
 # When the SERVER_BASED_SEARCH tag is enabled the search engine will be
 # implemented using a web server instead of a web client using JavaScript. There
@@ -2029,7 +2029,7 @@ COMPACT_LATEX          = NO
 # The default value is: a4.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-PAPER_TYPE             = a4wide
+PAPER_TYPE             = a4
 
 # The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names
 # that should be included in the LaTeX output. The package can be specified just

diff --git a/Makefile b/Makefile
@@ -22,6 +22,13 @@ PSP_FW_VERSION  = 371
 LIB_DIR         := lib
 SOURCE_DIR      := src
 
+# Single source of truth for the version: OSL_VERSION in src/oslib.h.
+# Exported so that Doxygen can pick it up through PROJECT_NUMBER.
+# NOTE: the pattern deliberately avoids a literal '#', because make 3.81
+# (shipped on macOS) strips everything after it, even inside $(shell ...).
+OSL_VERSION     := $(shell sed -n 's/.*OSL_VERSION[[:space:]]\{1,\}"\([^"]*\)".*/\1/p' $(SOURCE_DIR)/oslib.h | head -1)
+export OSL_VERSION
+
 #----------------------------------------------------------------------------
 #   Source to make
 #   --------------
@@ -270,7 +277,8 @@ release: lib
 ghpages: gendoc
 	rm -rf /tmp/ghpages
 	mkdir -p /tmp/ghpages
-	cp -Rv doc/html/* /tmp/ghpages
+	cp -R doc/html/. /tmp/ghpages
+	touch /tmp/ghpages/.nojekyll
 	cd /tmp/ghpages && \
 		git init && \
 		git config user.name "$${GIT_AUTHOR_NAME:-github-actions}" && \

diff --git a/doc/mainpage.txt b/doc/mainpage.txt
@@ -3,15 +3,15 @@
 
     \section intro Introduction
 
-    Welcome to the OldSchool Library (OSLib) documentation! This comprehensive guide is intended to help you navigate and utilize the various functions and features provided by OSLib. To get started, you can access the function reference by clicking on the "Modules" tab in the navigation menu.
+    Welcome to the OldSchool Library (OSLib) documentation! This comprehensive guide is intended to help you navigate and utilize the various functions and features provided by OSLib. To get started, you can access the function reference by clicking on the "Topics" tab in the navigation menu, or search for a specific symbol using the search box.
 
-    This documentation also includes a selection of tutorials designed to help you understand and make the most of OSLib's capabilities. If you are new to PSP development, it is highly recommended that you first explore the resources available on the official PSPDev site: [PSPDev Official Site](https://pspdev.github.io). There, you will find a variety of beginner-friendly tutorials to get you up and running.
+    Alongside the function reference, this documentation includes background articles on specific topics, such as \ref swizzling "image swizzling". If you are new to PSP development, it is highly recommended that you first explore the resources available on the official PSPDev site: [PSPDev Official Site](https://pspdev.github.io). There, you will find a variety of beginner-friendly tutorials to get you up and running.
 
     Please note that the documentation you are currently reading is intended for more advanced users who already have a foundational understanding of PSP development.
 
     \section concepts Key Concepts
 
-    As mentioned earlier, this documentation is tailored for users with prior experience in PSP development. If you are a beginner, we strongly encourage you to visit the official OSLib site, where you will find excellent tutorials created by Yodajr. These tutorials provide a great starting point for anyone new to the library.
+    As mentioned earlier, this documentation is tailored for users with prior experience in PSP development. If you are a beginner, the [OSLib repository on GitHub](https://github.com/dogo/oslib) is the best starting point: it holds the README, the changelog and a set of ready-to-build samples under `samples/` covering audio, drawing, text and font rendering, maps, networking, dialogs and save/load.
 
     For more advanced topics, such as optimizing image rendering using swizzling, please refer to the detailed explanations provided in the \ref swizzling "What is image swizzling?" section.
 */

diff --git a/src/browser.h b/src/browser.h
@@ -1,6 +1,12 @@
 #ifndef BROWSER_H
 #define BROWSER_H
 
+/** @file browser.h
+ *  @brief Internet browser functions in OSLib.
+ *
+ *  This file provides access to Sony's internet browser utility.
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif

diff --git a/src/dialog.h b/src/dialog.h
@@ -1,6 +1,13 @@
 #ifndef DIALOG_H
 #define DIALOG_H
 
+/** @file dialog.h
+ *  @brief Sony dialog functions in OSLib.
+ *
+ *  This file provides access to Sony's PSP dialogs, such as message dialogs,
+ *  error dialogs and the network configuration dialog.
+ */
+
 /** @defgroup Dialogs Dialogs
  *  @{
  *  @brief Functions to display Sony's dialogs.

diff --git a/src/drawing.h b/src/drawing.h
@@ -1,6 +1,14 @@
 #ifndef _OSL_DRAWING_H_
 #define _OSL_DRAWING_H_
 
+/** @file drawing.h
+ *  @brief Drawing and image handling functions in OSLib.
+ *
+ *  This file provides the 2D drawing API: screen and drawbuffer management,
+ *  colors, shapes, low level GU vertex types, and the complete image system
+ *  (loading, placement, manipulation, palettes, pixel access and sprites).
+ */
+
 /* Include auto-generated config only when built with CMake */
 #if __has_include("osl_config.h")
 #include "osl_config.h"
@@ -791,7 +799,7 @@ extern void oslUnswizzleTexture(u8 *out, const u8 *in, unsigned int width, unsig
  * The tile is defined by its top-left corner (`u`, `v`) and its size (`tX`, `tY`). The destination position on the screen is specified
  * by (`x`, `y`).
  *
- * @note This function is deprecated and should not be used in new code. It may be removed in future versions.
+ * @deprecated This function is deprecated and should not be used in new code. It may be removed in future versions.
  *
  * @param u The x-coordinate of the top-left corner of the tile in the texture.
  * @param v The y-coordinate of the top-left corner of the tile in the texture.
@@ -1420,7 +1428,10 @@ extern void oslDrawImage(OSL_IMAGE *img);
  *    Pointer to the `OSL_IMAGE` structure representing the image to be drawn.
  *
  * \note
- *    This function is maintained for compatibility with older code. For new code, use `oslDrawImage` instead. Ensure the image is properly initialized and its position is correctly set before calling this function.
+ *    Ensure the image is properly initialized and its position is correctly set before calling this function.
+ *
+ * \deprecated
+ *    This function is maintained only for compatibility with older code. Use `oslDrawImage` instead.
  */
 extern void oslDrawImageSimple(OSL_IMAGE *img);
 

diff --git a/src/keys.h b/src/keys.h
@@ -1,6 +1,14 @@
 #ifndef _OSL_KEYS_H_
 #define _OSL_KEYS_H_
 
+/** @file keys.h
+ *  @brief Controller handling functions in OSLib.
+ *
+ *  This file provides the controller API: reading the digital keys and the
+ *  analog stick, the key auto-repeat feature, and the analog to D-pad
+ *  conversion.
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -18,6 +26,7 @@ extern "C" {
  * This union represents the state of the buttons on a controller.
  */
 typedef union {
+	/** @brief Individual button bits, ordered as in the `value` field. */
 	struct {
 		int select : 1; //!< Select button.
 		int reserved1 : 2; //!< Reserved for padding, do not use.
@@ -68,9 +77,19 @@ typedef struct {
 
 /**
  * @enum OSL_KEY_BITS
- * @brief Bit number for each key in the 'value' field.
+ * @brief One-based key identifiers, as used by #oslMake3Buttons.
+ *
+ * These values are **not** bit numbers: each one is the bit position of the key in
+ * the `value` field of #OSL_KEYLIST **plus one**, so that the value 0 can be used to
+ * mean "no key". To build a mask from one of them, shift by `value - 1`:
+ *
+ * @code
+ * if (osl_keys->pressed.value & (1 << (OSL_KEY_CROSS - 1))) { ... }
+ * @endcode
  *
- * This enumeration defines the bit positions for each key in the `value` field of `OSL_KEYLIST`.
+ * To test a key directly, prefer the ready-made masks in #OSL_KEY_MASKS
+ * (`OSL_KEYMASK_CROSS`) or the named bitfields of #OSL_KEYLIST
+ * (`osl_keys->pressed.cross`).
  */
 enum OSL_KEY_BITS {
 	OSL_KEY_SELECT = 1,        //!< Select key.
@@ -215,6 +234,7 @@ extern void oslFlushKey();
  * This union represents the state of the buttons on a remote controller.
  */
 typedef union {
+	/** @brief Individual remote button bits, ordered as in the `value` field. */
 	struct {
 		int rmplaypause : 1; //!< Play/Pause button.
 		int reserved1 : 1; //!< Reserved for padding, do not use.

diff --git a/src/net.h b/src/net.h
@@ -4,6 +4,13 @@
 #include <sys/select.h>
 #include <pspnet_apctl.h>
 
+/** @file net.h
+ *  @brief Network functions in OSLib.
+ *
+ *  This file provides the networking API: WLAN handling, access point
+ *  connection and socket operations on the PSP.
+ */
+
 /**
  * @defgroup Network Network
  * @{

diff --git a/src/osk.h b/src/osk.h
@@ -1,6 +1,13 @@
 #ifndef OSK_H
 #define OSK_H
 
+/** @file osk.h
+ *  @brief On-Screen Keyboard functions in OSLib.
+ *
+ *  This file provides access to Sony's On-Screen Keyboard (OSK), used to let
+ *  the user enter text.
+ */
+
 /** @defgroup OSK On-Screen Keyboard
     @{
     Functions to display Sony's On Screen Keyboard.

diff --git a/src/oslmath.h b/src/oslmath.h
@@ -1,6 +1,14 @@
 #ifndef __OSL_MATH_H__
 #define __OSL_MATH_H__
 
+/** @file oslmath.h
+ *  @brief VFPU accelerated math functions in OSLib.
+ *
+ *  This file provides mathematical functions that leverage the PSP's Vector
+ *  Floating Point Unit (VFPU). They are based on the `libpspmath` library
+ *  (version 4) by MrMr[iCE].
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif

diff --git a/src/saveload.h b/src/saveload.h
@@ -1,6 +1,13 @@
 #ifndef SAVELOAD_H
 #define SAVELOAD_H
 
+/** @file saveload.h
+ *  @brief Save and load functions in OSLib.
+ *
+ *  This file provides access to Sony's save and load screens, used to read and
+ *  write save data in the PSP savedata format.
+ */
+
 /** @defgroup saveload Save and Load
  *  @brief Functions to use the save and load screen.
  *  @{