core: 实现窗口分层栈维护函数

src/core/layer.h

@@ -20,11 +20,41 @@ typedef struct layer_stack_t {
   size_t capacity;
 } layer_stack_t;
 
-void layer_stack_init(layer_stack_t *layer);
-void layer_stack_reset(layer_stack_t *layer);
+/**
+ * @brief 释放层栈内部资源并重置为空状态。
+ * @param layer 目标层栈。
+ */
+void layer_stack_cleanup(layer_stack_t *layer);
+
+/**
+ * @brief 在该层栈顶部追加一个窗口。
+ * @param layer 目标层栈。
+ * @param window 待追加的窗口 ID。
+ */
 void layer_stack_append(layer_stack_t *layer, window_id_t window);
-void layer_stack_remove(layer_stack_t *layer, window_id_t window);
-void layer_stack_raise(layer_stack_t *layer, window_id_t window);
-void layer_stack_lower(layer_stack_t *layer, window_id_t window);
+
+/**
+ * @brief 删除指定窗口。
+ * @param layer 目标层栈。
+ * @param window 待删除的窗口 ID。
+ * @return 找到并删除窗口时返回 true，否则返回 false。
+ */
+bool layer_stack_remove(layer_stack_t *layer, window_id_t window);
+
+/**
+ * @brief 将指定窗口提升到该层栈顶。
+ * @param layer 目标层栈。
+ * @param window 待提升的窗口 ID。
+ * @return 仅在窗口存在且顺序发生变化时返回 true，否则返回 false。
+ */
+bool layer_stack_raise(layer_stack_t *layer, window_id_t window);
+
+/**
+ * @brief 将指定窗口下沉到该层栈底。
+ * @param layer 目标层栈。
+ * @param window 待下沉的窗口 ID。
+ * @return 仅在窗口存在且顺序发生变化时返回 true，否则返回 false。
+ */
+bool layer_stack_lower(layer_stack_t *layer, window_id_t window);
 
 layer_type_t layer_classify(const window_props_t *props);