Update documentation

README.md

@@ -1,28 +1,154 @@
 [![Publish Docker Image](https://github.com/wiiu-env/libnotifications/actions/workflows/push_image.yml/badge.svg)](https://github.com/wiiu-env/libnotifications/actions/workflows/push_image.yml)
 
 # libnotifications
-Requires the [NotificationModule](https://github.com/wiiu-env/NotificationModule) to be running via [WUMSLoader](https://github.com/wiiu-env/WUMSLoader).
-Requires [wut](https://github.com/devkitPro/wut) for building.
-Install via `make install`.
 
-## Usage
-Make also sure to define 
+A Wii U homebrew library for displaying system-wide notifications.
+
+**Prerequisites:**
+* **Runtime:** Requires the [NotificationModule](https://github.com/wiiu-env/NotificationModule) to be running via [WUMSLoader](https://github.com/wiiu-env/WUMSLoader).
+* **Build:** Requires [wut](https://github.com/devkitPro/wut) for building.
+
+## Installation
+
+You can install the library via the Makefile:
+```
+make install
+```
+## Build Setup
+
+To use this library in your project, ensure your `Makefile` or build system is configured correctly.
+
+1.  **Define WUMS_ROOT**:
 ```
 WUMS_ROOT := $(DEVKITPRO)/wums
 ```
-and add `-lnotifications` to `LIBS` and `$(WUMS_ROOT)` to `LIBDIRS`.
+2.  **Update Library Flags**:
+Add `-lnotifications` to your `LIBS` and include the WUMS path in `LIBDIRS`.
+```
+LIBS    := ... -lnotifications
+LIBDIRS := ... $(WUMS_ROOT)
+```
+## Usage Examples
+
+Include the main header to access the API:
+```
+#include <notifications/notifications.h>
+```
+### 1. Initialization
+You **must** initialize the library before calling any notification functions. It is good practice to check the specific error code to diagnose issues (e.g., missing module).
+```
+void setup() {
+    NotificationModuleStatus status = NotificationModule_InitLibrary();
+
+    if (status != NOTIFICATION_MODULE_RESULT_SUCCESS) {
+        if (status == NOTIFICATION_MODULE_RESULT_MODULE_NOT_FOUND) {
+            // Critical Error: WUMSLoader or NotificationModule is not running.
+        } else if (status == NOTIFICATION_MODULE_RESULT_UNSUPPORTED_VERSION) {
+            // The installed NotificationModule version is incompatible.
+        }
+        // Do not proceed with using the library.
+        return;
+    }
+}
+
+void cleanup() {
+    NotificationModule_DeInitLibrary();
+}
+```
+### 2. Simple Notifications
+Even simple notifications can fail if the overlay isn't ready or memory is low.
+
+**Info Notification (Fades out automatically):**
+```
+if (const auto status = NotificationModule_AddInfoNotification("File saved successfully!") != NOTIFICATION_MODULE_RESULT_SUCCESS) {
+    // Failed to display notification
+    OSReport("Failed to display notification: Error %s\n", NotificationModule_GetStatusStr(status));
+}
+```
 
-Include `<notifications/notifications.h>` to get access to the NotificationModule functions, after calling `NotificationModule_InitLibrary()`.
 
-## Use this lib in Dockerfiles.
-A prebuilt version of this lib can found on dockerhub. To use it for your projects, add this to your Dockerfile.
+**Error Notification (Shakes and fades out):**
 ```
-[...]
+if (const auto status = NotificationModule_AddErrorNotification("Connection failed!") != NOTIFICATION_MODULE_RESULT_SUCCESS) {
+    // Failed to display notification
+    OSReport("Failed to display notification: Error %s\n", NotificationModule_GetStatusStr(status));
+}
+```
+### 3. Dynamic Notifications
+For dynamic notifications, it is critical to ensure the notification was successfully created before attempting to update or finish it.
+```
+NotificationModuleHandle handle;
+NotificationModuleStatus status = NotificationModule_AddDynamicNotification("Downloading... 0%", &handle);
+
+if (status == NOTIFICATION_MODULE_RESULT_SUCCESS) {
+    // 1. Update the text during your process
+    NotificationModule_UpdateDynamicNotificationText(handle, "Downloading... 50%");
+    [...]
+    // 2. Finish it when done (fades out after 2 seconds)
+    NotificationModule_FinishDynamicNotification(handle, 2.0f);
+} else {
+    // Handle failure (e.g., NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED)
+    // Note: 'handle' is undefined here and should not be used.
+}
+```
+
+This example shows how to trigger a callback function when a dynamic notification finishes.
+```
+// 1. Define the callback
+void OnFinished(NotificationModuleHandle handle, void* context) {
+    // called when the notification finished fading out.
+}
+
+// 2. Usage
+void ShowProgress() {
+    NotificationModuleHandle handle;
+    int myData = 42; // Example context data
+
+    NotificationModuleStatus status = NotificationModule_AddDynamicNotificationWithCallback(
+        "Loading... 0%", 
+        &handle, 
+        OnFinished, 
+        (void *) &myData
+    );
+
+    if (status == NOTIFICATION_MODULE_RESULT_SUCCESS) {
+        // Update status...
+        NotificationModule_UpdateDynamicNotificationText(handle, "Loading... 100%");
+
+        // Finish (triggers callback after fade out)
+        NotificationModule_FinishDynamicNotification(handle, 1.5f);
+    }
+}
+```
+### 4. Customizing Defaults
+Setting default values returns a status code which can indicate invalid arguments (e.g., passing a float when an int is expected).
+```
+// Define a custom color
+NMColor green = {0, 128, 0, 255};
+
+NotificationModuleStatus status = NotificationModule_SetDefaultValue(
+    NOTIFICATION_MODULE_NOTIFICATION_TYPE_INFO,
+    NOTIFICATION_MODULE_DEFAULT_OPTION_BACKGROUND_COLOR,
+    green
+);
+
+if (status != NOTIFICATION_MODULE_RESULT_SUCCESS) {
+    // This might happen if the type or option is invalid.
+}
+```
+## Docker Integration
+
+A prebuilt version of this lib can found on dockerhub. To use it for your projects, add this to your `Dockerfile`.
+```
+# ... previous stages ...
 COPY --from=ghcr.io/wiiu-env/libnotifications:[tag] /artifacts $DEVKITPRO
-[...]
+# ... build stages ...
 ```
-Replace [tag] with a tag you want to use, a list of tags can be found [here](https://github.com/wiiu-env/libnotifications/pkgs/container/libnotifications/versions). 
-It's highly recommended to pin the version to the **latest date** instead of using `latest`.
+> **Note:** It is highly recommended to pin the version to a specific date tag (e.g., `:20230101`) rather than using `:latest` to ensure build reproducibility. Available tags can be found [here](https://github.com/wiiu-env/libnotifications/pkgs/container/libnotifications/versions).
 
-## Format the code via docker
-`docker run --rm -v ${PWD}:/src ghcr.io/wiiu-env/clang-format:13.0.0-2 -r ./source ./include -i`
+## Development
+
+**Format Code:**
+```
+docker run --rm -v ${PWD}:/src ghcr.io/wiiu-env/clang-format:13.0.0-2 -r ./source ./include -i
+```