From 2ffdc6f539c3c6a21afc7f8393f066a9cad1e745 Mon Sep 17 00:00:00 2001
From: apio <blobs.trading@gmail.com>
Date: Mon, 7 Aug 2023 19:16:43 +0200
Subject: [PATCH] libui: Document ui::Font

---
 libui/include/ui/Font.h | 56 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/libui/include/ui/Font.h b/libui/include/ui/Font.h
index 2f2962cb..a2614638 100644
--- a/libui/include/ui/Font.h
+++ b/libui/include/ui/Font.h
@@ -8,29 +8,85 @@
 
 namespace ui
 {
+    /**
+     * @brief A class holding PSF font data, used for direct rendering of glyphs into a canvas.
+     */
     class Font : public Shareable
     {
       public:
+        /**
+         * @brief An enum used to select a font weight when loading a font.
+         */
         enum FontWeight
         {
             Regular,
             Bold,
         };
 
+        /**
+         * @brief Load a Font object from a font file.
+         *
+         * @param path The full path to the font file.
+         * @return Result<SharedPtr<Font>> An error, or the loaded Font object.
+         */
         static Result<SharedPtr<Font>> load(const os::Path& path);
+
+        /**
+         * @brief Load a system font by name.
+         *
+         * @param name The name of the font to load (the default system font is "Tamsyn").
+         * @param weight The weight of the font (regular or bold).
+         * @return Result<SharedPtr<Font>> An error, or the loaded Font object.
+         */
         static Result<SharedPtr<Font>> load_builtin(StringView name, FontWeight weight);
 
+        /**
+         * @brief Return a pointer to the system's default font.
+         *
+         * @return SharedPtr<Font> The default font.
+         */
         static SharedPtr<Font> default_font();
+
+        /**
+         * @brief Return a pointer to the system's default bold font.
+         *
+         * @return SharedPtr<Font> The default bold font.
+         */
         static SharedPtr<Font> default_bold_font();
 
+        /**
+         * @brief Render a single Unicode code point into a canvas, using this font's glyphs.
+         *
+         * @param codepoint The code point to render.
+         * @param color The color to draw the code point in.
+         * @param canvas The canvas to use.
+         */
         void render(wchar_t codepoint, ui::Color color, ui::Canvas& canvas);
+
+        /**
+         * @brief Render a Unicode text string into a canvas, using this font's glyphs.
+         *
+         * @param text The string to render (must be null-terminated).
+         * @param color The color to draw the code point in.
+         * @param canvas The canvas to use.
+         */
         void render(const wchar_t* text, ui::Color color, ui::Canvas& canvas);
 
+        /**
+         * @brief Return the width of this font's glyphs.
+         *
+         * @return int The width.
+         */
         int width() const
         {
             return m_psf_header.width;
         }
 
+        /**
+         * @brief Return the height of this font's glyphs.
+         *
+         * @return int The height.
+         */
         int height() const
         {
             return m_psf_header.height;