feat: better compile; material token access; gui color scheme galleries

Author: Charliechen114514

base/include/base/hash/constexpr_fnv1a.hpp

@@ -61,8 +61,8 @@ inline constexpr uint32_t fnv1a32_prime = 16777619U;
  * The FNV-1a algorithm provides excellent distribution and
  * minimal collisions for string identifiers.
  *
- * @param  str Null-terminated string to hash.
- * @param  seed Starting hash value (default: FNV offset basis).
+ * @param[in]  str Null-terminated string to hash.
+ * @param[in]  seed Starting hash value (default: FNV offset basis).
  *
  * @return     64-bit hash value.
  *
@@ -91,8 +91,8 @@ constexpr uint64_t fnv1a64(const char* str, uint64_t seed = fnv1a64_offset_basis
 /**
  * @brief  FNV-1a 64-bit hash for std::string_view (runtime/constexpr).
  *
- * @param  sv String view to hash.
- * @param  seed Starting hash value (default: FNV offset basis).
+ * @param[in]  sv String view to hash.
+ * @param[in]  seed Starting hash value (default: FNV offset basis).
  *
  * @return    64-bit hash value.
  *
@@ -110,8 +110,8 @@ constexpr uint64_t fnv1a64(std::string_view sv, uint64_t seed = fnv1a64_offset_b
 /**
  * @brief  FNV-1a 32-bit hash constexpr implementation.
  *
- * @param  str Null-terminated string to hash.
- * @param  seed Starting hash value (default: FNV offset basis).
+ * @param[in]  str Null-terminated string to hash.
+ * @param[in]  seed Starting hash value (default: FNV offset basis).
  *
  * @return     32-bit hash value.
  *
@@ -127,8 +127,8 @@ constexpr uint32_t fnv1a32(const char* str, uint32_t seed = fnv1a32_offset_basis
 /**
  * @brief  FNV-1a 32-bit hash for std::string_view.
  *
- * @param  sv String view to hash.
- * @param  seed Starting hash value (default: FNV offset basis).
+ * @param[in]  sv String view to hash.
+ * @param[in]  seed Starting hash value (default: FNV offset basis).
  *
  * @return    32-bit hash value.
  *

base/system/memory/private/linux_impl/linux_impl.hpp

@@ -0,0 +1,11 @@
+/**
+ * @file    linux_impl.hpp
+ * @brief   Linux-specific memory implementation.
+ *
+ * @author  Charliechen114514
+ * @date    2026-02-25
+ * @version 0.1
+ * @since   0.1
+ * @ingroup base_memory
+ */
+#pragma once

ui/core/material/cfmaterial_scheme.h

@@ -219,7 +219,7 @@ class CF_UI_EXPORT MaterialColorScheme : public ICFColorScheme {
     /**
      * @brief Query a color by name.
      *
-     * @param name Color token name (e.g., "md.primary").
+     * @param[in] name Color token name (e.g., "md.primary").
      * @return Reference to the QColor.
      *
      * @since 0.1
@@ -229,7 +229,7 @@ class CF_UI_EXPORT MaterialColorScheme : public ICFColorScheme {
     /**
      * @brief Query a color by name (const overload).
      *
-     * @param name Color token name.
+     * @param[in] name Color token name.
      * @return Copy of the QColor.
      *
      * @since 0.1

ui/core/token.hpp

@@ -35,6 +35,7 @@ namespace cf::ui::core {
 // Forward Declarations
 // =============================================================================
 class TokenRegistry;
+/// @brief Compile-time type-safe token with zero runtime overhead.
 template <typename T, uint64_t Hash> class StaticToken;
 
 // =============================================================================
@@ -126,11 +127,19 @@ struct TokenError {
  */
 template <typename T, uint64_t Hash> class StaticToken {
   public:
+    /// @brief Value type stored in this token.
     using value_type = T;
+
+    /// @brief Compile-time hash of the token name.
     static constexpr uint64_t hash_value = Hash;
 
+    /// @brief Default constructor is deleted.
     StaticToken() = delete;
+
+    /// @brief Copy constructor is deleted.
     StaticToken(const StaticToken&) = delete;
+
+    /// @brief Copy assignment operator is deleted.
     StaticToken& operator=(const StaticToken&) = delete;
 
     /**
@@ -302,7 +311,7 @@ class TokenRegistry {
      *
      * @tparam T Value type to store.
      * @param  name Token name.
-     * @param  value Value to store (will be copied).
+     * @param  value Value to store (copied).
      *
      * @return     Result containing void or TokenError.
      *
@@ -315,7 +324,7 @@ class TokenRegistry {
      *
      * @tparam T Value type to store.
      * @param  name Token name.
-     * @param  value Value to store (will be moved).
+     * @param  value Value to store (moved).
      *
      * @return     Result containing void or TokenError.
      *
@@ -448,11 +457,25 @@ class TokenRegistry {
 // Inline Implementations - StaticToken
 // =============================================================================
 
+/**
+ * @brief  Type-safe value accessor for registry.
+ *
+ * @return     cf::expected containing pointer to the token's value or TokenError.
+ *
+ * @since      0.1
+ */
 template <typename T, uint64_t Hash> auto StaticToken<T, Hash>::get()
     -> cf::expected<T*, TokenError> {
     return TokenRegistry::get().get<StaticToken<T, Hash>>();
 }
 
+/**
+ * @brief  Const version of value accessor.
+ *
+ * @return     cf::expected containing const pointer to the token's value or TokenError.
+ *
+ * @since      0.1
+ */
 template <typename T, uint64_t Hash> auto StaticToken<T, Hash>::get_const()
     -> cf::expected<const T*, TokenError> {
     return TokenRegistry::get().get_const<StaticToken<T, Hash>>();
@@ -826,7 +849,7 @@ class EmbeddedTokenRegistry {
      *
      * @tparam T Value type to store.
      * @param  name Token name.
-     * @param  value Value to store (will be copied).
+     * @param  value Value to store (copied).
      *
      * @return     Result containing void or TokenError.
      *
@@ -839,7 +862,7 @@ class EmbeddedTokenRegistry {
      *
      * @tparam T Value type to store.
      * @param  name Token name.
-     * @param  value Value to store (will be moved).
+     * @param  value Value to store (moved).
      *
      * @return     Result containing void or TokenError.
      *
@@ -1005,7 +1028,8 @@ inline const detail::TokenSlot* EmbeddedTokenRegistry::find_slot_const(uint64_t
 }
 
 template <typename T, typename... Args>
-auto EmbeddedTokenRegistry::register_dynamic(std::string_view name, Args&&... args) -> Result<void> {
+auto EmbeddedTokenRegistry::register_dynamic(std::string_view name, Args&&... args)
+    -> Result<void> {
     uint64_t hash = cf::hash::fnv1a64(name);
 
     std::unique_lock<std::shared_mutex> lock(registry_mutex_);
@@ -1027,7 +1051,8 @@ auto EmbeddedTokenRegistry::register_dynamic(std::string_view name, Args&&... ar
 }
 
 template <typename T>
-auto EmbeddedTokenRegistry::register_dynamic(std::string_view name, const T& value) -> Result<void> {
+auto EmbeddedTokenRegistry::register_dynamic(std::string_view name, const T& value)
+    -> Result<void> {
     uint64_t hash = cf::hash::fnv1a64(name);
 
     std::unique_lock<std::shared_mutex> lock(registry_mutex_);