Update doxygen

.gitignore

@@ -27,3 +27,5 @@ packages/
 
 # Resources bin
 *.aps
+
+docs/

Doxyfile

@@ -0,0 +1,86 @@
+# Doxyfile 1.8.16
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+
+PROJECT_NAME           = "Kiwano Engine"
+PROJECT_NUMBER         = v1.0.0
+PROJECT_BRIEF          =
+PROJECT_LOGO           = logo/logo_square_tiny.png
+
+DOXYFILE_ENCODING      = UTF-8
+CREATE_SUBDIRS         = YES
+
+OUTPUT_LANGUAGE        = Chinese
+OUTPUT_DIRECTORY       = docs/
+
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = NO
+
+HIDE_UNDOC_MEMBERS     = YES
+HIDE_UNDOC_CLASSES     = NO
+
+SHOW_INCLUDE_FILES     = YES
+SHOW_USED_FILES        = NO
+SHOW_FILES             = NO
+SHOW_NAMESPACES        = YES
+
+#---------------------------------------------------------------------------
+# Configuration options related to the input files
+#---------------------------------------------------------------------------
+
+INPUT                  = src/
+INPUT_ENCODING         = gb2312
+FILE_PATTERNS          = *.c \
+                         *.cc \
+                         *.cxx \
+                         *.cpp \
+                         *.c++ \
+                         *.h \
+                         *.hh \
+                         *.hxx \
+                         *.hpp \
+                         *.h++ \
+
+RECURSIVE              = YES
+EXCLUDE                = src/3rd-party
+
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+PREDEFINED             = KGE_API=
+
+# The INCLUDE_PATH tag can be used to specify one or more directories that
+# contain include files that are not input files but should be processed by the
+# preprocessor.
+# This tag requires that the tag SEARCH_INCLUDES is set to YES.
+
+INCLUDE_PATH           =
+INCLUDE_FILE_PATTERNS  =
+
+#---------------------------------------------------------------------------
+# Configuration options related to the HTML output
+#---------------------------------------------------------------------------
+
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+
+HTML_HEADER            =
+HTML_FOOTER            =
+HTML_STYLESHEET        =
+HTML_EXTRA_STYLESHEET  =
+
+GENERATE_TREEVIEW      = YES
+ENUM_VALUES_PER_LINE   = 4
+TREEVIEW_WIDTH         = 250
+
+#---------------------------------------------------------------------------
+# Configuration options related to the LATEX output
+#---------------------------------------------------------------------------
+
+GENERATE_LATEX         = NO

src/3rd-party/OuterC/oc/intrusive_list.h

@@ -31,7 +31,7 @@ private:
 	pointer_type prev_;
 	pointer_type next_;
 
-	friend class intrusive_list<_Ty>;
+	friend class intrusive_list<_Ty, _PTy>;
 };
 
 

src/kiwano-audio/AudioEngine.h

@@ -33,7 +33,7 @@ namespace kiwano
 			: public Singleton<AudioEngine>
 			, public ComponentBase
 		{
-			OC_DECLARE_SINGLETON(AudioEngine);
+			friend Singleton<AudioEngine>;
 
 		public:
 			// 开启设备

src/kiwano-imgui/ImGuiModule.h

@@ -32,7 +32,7 @@ namespace kiwano
 			, public UpdateComponent
 			, public EventComponent
 		{
-			OC_DECLARE_SINGLETON(ImGuiModule);
+			friend Singleton<ImGuiModule>;
 
 		private:
 			void Init(HWND hwnd);

src/kiwano-network/HttpClient.h

@@ -32,7 +32,7 @@ namespace kiwano
 			: public Singleton<HttpClient>
 			, public ComponentBase
 		{
-			OC_DECLARE_SINGLETON(HttpClient);
+			friend Singleton<HttpClient>;
 
 		public:
 			void Send(HttpRequestPtr request);

src/kiwano/core/Component.h

@@ -27,11 +27,19 @@ namespace kiwano
 	class RenderTarget;
 	class Event;
 
-	// 基础组件
+	/**
+	* \~chinese
+	* @brief 基础功能组件
+	*/
 	class KGE_API ComponentBase
 	{
 	public:
+		/// \~chinese
+		/// @brief 启动组件
 		virtual void SetupComponent() = 0;
+
+		/// \~chinese
+		/// @brief 销毁组件
 		virtual void DestroyComponent() = 0;
 
 		bool Check(const int flag);
@@ -44,15 +52,25 @@ namespace kiwano
 	};
 
 
-	// 渲染支持组件
+	/**
+	* \~chinese
+	* @brief 渲染支持组件
+	*/
 	class KGE_API RenderComponent
 		: public virtual ComponentBase
 	{
 	public:
+		/// \~chinese
+		/// @brief 渲染前
 		virtual void BeforeRender() {}
 
-		virtual void OnRender(RenderTarget*) {}
+		/// \~chinese
+		/// @brief 渲染时
+		/// @param rt 渲染目标
+		virtual void OnRender(RenderTarget* rt) {}
 
+		/// \~chinese
+		/// @brief 渲染后
 		virtual void AfterRender() {}
 
 	public:
@@ -62,15 +80,25 @@ namespace kiwano
 	};
 
 
-	// 更新支持组件
+	/**
+	* \~chinese
+	* @brief 更新支持组件
+	*/
 	class KGE_API UpdateComponent
 		: public virtual ComponentBase
 	{
 	public:
+		/// \~chinese
+		/// @brief 更新前
 		virtual void BeforeUpdate() {}
 
-		virtual void OnUpdate(Duration) {}
+		/// \~chinese
+		/// @brief 更新时
+		/// @param dt 间隔时间
+		virtual void OnUpdate(Duration dt) {}
 
+		/// \~chinese
+		/// @brief 更新后
 		virtual void AfterUpdate() {}
 
 	public:
@@ -80,13 +108,21 @@ namespace kiwano
 	};
 
 
-	// 事件支持组件
+	/**
+	* \~chinese
+	* @brief 事件支持组件
+	*/
 	class KGE_API EventComponent
 		: public virtual ComponentBase
 	{
 	public:
-		virtual void HandleEvent(Event&) {}
+		/// \~chinese
+		/// @brief 事件处理
+		/// @param evt 事件
+		virtual void HandleEvent(Event& evt) {}
 
+		/// \~chinese
+		/// @brief Windows 消息处理
 		virtual void HandleMessage(HWND, UINT32, WPARAM, LPARAM) {}
 
 	public:

src/kiwano/core/Logger.h

@@ -55,7 +55,7 @@ namespace kiwano
 	class KGE_API Logger
 		: public Singleton<Logger>
 	{
-		OC_DECLARE_SINGLETON(Logger);
+		friend Singleton<Logger>;
 
 	public:
 		// 显示或关闭控制台

src/kiwano/core/keys.h

@@ -23,103 +23,105 @@
 
 namespace kiwano
 {
-	// 報炎梓囚
+	/// \~chinese
+	/// @brief 鼠标按键
 	struct MouseButton
 	{
 		typedef int Value;
 
 		enum : Value
 		{
-			Left	= VK_LBUTTON,	// 報炎恣囚
-			Right	= VK_RBUTTON,	// 報炎嘔囚
-			Middle	= VK_MBUTTON	// 報炎嶄囚
+			Left	= VK_LBUTTON,	///< 鼠标左键
+			Right	= VK_RBUTTON,	///< 鼠标右键
+			Middle	= VK_MBUTTON	///< 鼠标中键
 		};
 	};
 
 
-	// 梓囚囚峙
+	/// \~chinese
+	/// @brief 按键键值
 	struct KeyCode
 	{
 		typedef int Value;
 
 		enum : Value
 		{
-			Unknown = 0,
-			Up		= VK_UP,
-			Left	= VK_LEFT,
-			Right	= VK_RIGHT,
-			Down	= VK_DOWN,
-			Enter	= VK_RETURN,
-			Space	= VK_SPACE,
-			Esc		= VK_ESCAPE,
-			Ctrl	= VK_CONTROL,
-			Shift	= VK_SHIFT,
-			Alt		= VK_MENU,
-			Tab		= VK_TAB,
-			Delete	= VK_DELETE,
-			Back	= VK_BACK,
+			Unknown = 0,			///< 未知
+			Up		= VK_UP,		///< 上键
+			Left	= VK_LEFT,		///< 左键
+			Right	= VK_RIGHT,		///< 右键
+			Down	= VK_DOWN,		///< 下键
+			Enter	= VK_RETURN,	///< 回车键
+			Space	= VK_SPACE,		///< 空格键
+			Esc		= VK_ESCAPE,	///< 退出键
+			Ctrl	= VK_CONTROL,	///< CTRL键
+			Shift	= VK_SHIFT,		///< SHIFT键
+			Alt		= VK_MENU,		///< ALT键
+			Tab		= VK_TAB,		///< TAB键
+			Delete	= VK_DELETE,	///< 删除键
+			Back	= VK_BACK,		///< 退格键
 
-			A = 0x41,
-			B,
-			C,
-			D,
-			E,
-			F,
-			G,
-			H,
-			I,
-			J,
-			K,
-			L,
-			M,
-			N,
-			O,
-			P,
-			Q,
-			R,
-			S,
-			T,
-			U,
-			V,
-			W,
-			X,
-			Y,
-			Z,
+			A = 0x41,				///< A键
+			B,						///< B键
+			C,						///< C键
+			D,						///< D键
+			E,						///< E键
+			F,						///< F键
+			G,						///< G键
+			H,						///< H键
+			I,						///< I键
+			J,						///< J键
+			K,						///< K键
+			L,						///< L键
+			M,						///< M键
+			N,						///< N键
+			O,						///< O键
+			P,						///< P键
+			Q,						///< Q键
+			R,						///< R键
+			S,						///< S键
+			T,						///< T键
+			U,						///< U键
+			V,						///< V键
+			W,						///< W键
+			X,						///< X键
+			Y,						///< Y键
+			Z,						///< Z键
 
-			Num0 = 0x30,
-			Num1,
-			Num2,
-			Num3,
-			Num4,
-			Num5,
-			Num6,
-			Num7,
-			Num8,
-			Num9,
+			Num0 = 0x30,			///< 数字0键
+			Num1,					///< 数字1键
+			Num2,					///< 数字2键
+			Num3,					///< 数字3键
+			Num4,					///< 数字4键
+			Num5,					///< 数字5键
+			Num6,					///< 数字6键
+			Num7,					///< 数字7键
+			Num8,					///< 数字8键
+			Num9,					///< 数字9键
 
-			Numpad0 = VK_NUMPAD0,
-			Numpad1,
-			Numpad2,
-			Numpad3,
-			Numpad4,
-			Numpad5,
-			Numpad6,
-			Numpad7,
-			Numpad8,
-			Numpad9,
+			Numpad0 = VK_NUMPAD0,	///< 数字小键盘0键
+			Numpad1,				///< 数字小键盘1键
+			Numpad2,				///< 数字小键盘2键
+			Numpad3,				///< 数字小键盘3键
+			Numpad4,				///< 数字小键盘4键
+			Numpad5,				///< 数字小键盘5键
+			Numpad6,				///< 数字小键盘6键
+			Numpad7,				///< 数字小键盘7键
+			Numpad8,				///< 数字小键盘8键
+			Numpad9,				///< 数字小键盘9键
 
-			F1 = VK_F1,
-			F2,
-			F3,
-			F4,
-			F5,
-			F6,
-			F7,
-			F8,
-			F9,
-			F10,
-			F11,
-			F12,
+			F1 = VK_F1,				///< F1键
+			F2,						///< F2键
+			F3,						///< F3键
+			F4,						///< F4键
+			F5,						///< F5键
+			F6,						///< F6键
+			F7,						///< F7键
+			F8,						///< F8键
+			F9,						///< F9键
+			F10,					///< F10键
+			F11,					///< F11键
+			F12,					///< F12键
 		};
 	};
 }

src/kiwano/core/time.cpp

@@ -354,25 +354,24 @@ namespace kiwano
 		return dur * val;
 	}
 
-	Duration Duration::Parse(const String& str)
+	Duration Duration::Parse(const String& format)
 	{
-		bool		negative	= false;
-		size_t	len			= str.length();
-		size_t	pos			= 0;
-		Duration	ret;
+		bool negative = false;
+		size_t len = format.length();
+		size_t pos = 0;
+		Duration ret;
 
-		if (!std::regex_match(str.c_str(), duration_regex))
+		if (!std::regex_match(format.c_str(), duration_regex))
 		{
-			KGE_ERROR(L"Duration::Parse failed, invalid duration");
-			return ret;
+			throw std::runtime_error("Duration::Parse failed, invalid duration");
 		}
 
-		if (str.empty() || str == L"0") { return ret; }
+		if (format.empty() || format == L"0") { return ret; }
 
 		// ·ûºÅλ
-		if (str[0] == L'-' || str[0] == L'+')
+		if (format[0] == L'-' || format[0] == L'+')
 		{
-			negative = (str[0] == L'-');
+			negative = (format[0] == L'-');
 			pos++;
 		}
 
@@ -382,32 +381,34 @@ namespace kiwano
 			size_t i = pos;
 			for (; i < len; ++i)
 			{
-				wchar_t ch = str[i];
+				wchar_t ch = format[i];
 				if (!(ch == L'.' || L'0' <= ch && ch <= L'9'))
 				{
 					break;
 				}
 			}
 
-			String num_str = str.substr(pos, i - pos);
+			String num_str = format.substr(pos, i - pos);
 			pos = i;
 
-			KGE_ASSERT(!(num_str.empty() || num_str == L".") && "Duration::Parse failed, invalid duration");
+			if (num_str.empty() || num_str == L".")
+				throw std::runtime_error("Duration::Parse failed, invalid duration");
 
 			// µ¥Î»
 			for (; i < len; ++i)
 			{
-				wchar_t ch = str[i];
+				wchar_t ch = format[i];
 				if (ch == L'.' || L'0' <= ch && ch <= L'9')
 				{
 					break;
 				}
 			}
 
-			String unit_str = str.substr(pos, i - pos);
+			String unit_str = format.substr(pos, i - pos);
 			pos = i;
 
-			KGE_ASSERT(unit_map.find(unit_str) != unit_map.end() && "Duration::Parse failed, invalid duration");
+			if (unit_map.find(unit_str) == unit_map.end())
+				throw std::runtime_error("Duration::Parse failed, invalid duration");
 
 			double num = std::wcstod(num_str.c_str(), nullptr);
 			Duration unit = unit_map.at(unit_str);

src/kiwano/core/time.h

@@ -24,51 +24,98 @@
 
 namespace kiwano
 {
-	// 时间段
-	//
-	// 时间段表示法:
-	//     5 秒: time::Second * 5
-	//     1.5 小时: time::Hour * 1.5
-	//     3 小时 45 分 15 秒: time::Hour * 3 + time::Minute * 45 + time::Second * 15
-	// 在 VS2015 及更高版本可以使用 time literals:
-	//     5 秒: 5_s
-	//     1.5 小时: 1.5_h
-	//     3 小时 45 分 15 秒: 3_h + 45_m + 15_s
-	//
+	/**
+	* \~chinese
+	* @brief 时间段
+	* @details
+	*   时间段表示法:
+	*     5 秒: time::Second * 5
+	*     1.5 小时: time::Hour * 1.5
+	*     3 小时 45 分 15 秒: time::Hour * 3 + time::Minute * 45 + time::Second * 15
+	*   在 VS2015 及更高版本可以使用 time literals:
+	*     5 秒: 5_s
+	*     1.5 小时: 1.5_h
+	*     3 小时 45 分 15 秒: 3_h + 45_m + 15_s
+	*/
 	struct KGE_API Duration
 	{
+		/// \~chinese
+		/// @brief 构造时间段
 		Duration();
 
+		/// \~chinese
+		/// @brief 构造时间段
+		/// @param milliseconds 毫秒数
 		Duration(
 			long milliseconds
 		);
 
-		// 转化为毫秒
+		/// \~chinese
+		/// @brief 获取毫秒数
+		/// @return 毫秒数
 		long Milliseconds() const;
 
-		// 转化为秒
+		/// \~chinese
+		/// @brief 获取秒数
+		/// @return 秒数
 		float Seconds() const;
 
-		// 转化为分钟
+		/// \~chinese
+		/// @brief 获取分钟数
+		/// @return 分钟数
 		float Minutes() const;
 
-		// 转化为小时
+		/// \~chinese
+		/// @brief 获取小时数
+		/// @return 小时数
 		float Hours() const;
 
-		// 时长是否是零
+		/// \~chinese
+		/// @brief 时长是否是零
+		/// @return 若时长是零，返回true
 		bool IsZero() const;
 
+		/// \~chinese
+		/// @brief 设置毫秒数
+		/// @param ms 毫秒数
 		void SetMilliseconds(long ms);
 
+		/// \~chinese
+		/// @brief 设置秒数
+		/// @param seconds 秒数
 		void SetSeconds(float seconds);
 
+		/// \~chinese
+		/// @brief 设置分钟数
+		/// @param minutes 分钟数
 		void SetMinutes(float minutes);
 
+		/// \~chinese
+		/// @brief 设置小时数
+		/// @param hours 小时数
 		void SetHours(float hours);
 
-		// 转为字符串
+		/// \~chinese
+		/// @brief 转为字符串
+		/// @return 格式化后的字符串
 		String ToString() const;
 
+		/// \~chinese
+		/// @brief 时间段格式化
+		/// @param format 格式
+		/// @details
+		///   时间段字符串允许是有符号的浮点数, 并且带有时间单位后缀
+		///   例如: "300ms", "-1.5h", "2h45m"
+		///   允许的时间单位有 "ms", "s", "m", "h"
+		/// @return 解析出的时间段
+		/// @throw std::runtime_error 传入了一个不合法的格式
+		static Duration Parse(const String& str);
+
+		static const Duration Ms;		///< 毫秒
+		static const Duration Second;	///< 秒
+		static const Duration Minute;	///< 分钟
+		static const Duration Hour;		///< 小时
+
 		bool operator== (const Duration &) const;
 		bool operator!= (const Duration &) const;
 		bool operator> (const Duration &) const;
@@ -107,37 +154,38 @@ namespace kiwano
 		friend const Duration operator/ (float, const Duration &);
 		friend const Duration operator/ (double, const Duration &);
 
-		// 时间段格式化
-		//
-		// 时间段字符串允许是有符号的浮点数, 并且带有时间单位后缀
-		// 例如: "300ms", "-1.5h", "2h45m"
-		// 允许的时间单位有 "ms", "s", "m", "h"
-		static Duration Parse(const String& parse_str);
-
-		static const Duration Ms;		// 毫秒
-		static const Duration Second;		// 秒
-		static const Duration Minute;		// 分钟
-		static const Duration Hour;		// 小时
-
 	private:
 		long milliseconds_;
 	};
 
 
-	// 时间
-	//
-	// 获取当前时间: Time now = Time::Now();
-	// 两时间相减, 得到一个 Duration 对象, 例如:
-	//     Time t1, t2;
-	//     int ms = (t2 - t1).Milliseconds();  // 获取两时间相差的毫秒数
-	// 
+	/**
+	* \~chinese
+	* @brief 时间
+	* @par 示例：
+	* @code
+	*   // 两时间相减, 可得到一个 Duration 对象
+	*   Time t1 = Time::Now();
+	*   // 等待一段时间后
+	*   Time t2 = Time::Now();
+	*   int ms = (t2 - t1).Milliseconds();  // 获取两时间相差的毫秒数
+	* @endcode
+	* @note 时间点与系统时钟无关，因此不能将时间点转化为时分秒
+	*/
 	struct KGE_API Time
 	{
 		Time();
 
-		// 是否是零时
+		/// \~chinese
+		/// @brief 是否是零时
+		/// @return 若是零时，返回true
 		bool IsZero() const;
 
+		/// \~chinese
+		/// @brief 获取当前时间
+		/// @return 当前时间
+		static Time Now() noexcept;
+
 		const Duration operator -(const Time&) const;
 
 		const Time operator +(const Duration &) const;
@@ -146,11 +194,6 @@ namespace kiwano
 		Time& operator +=(const Duration &);
 		Time& operator -=(const Duration &);
 
-		// 获取当前时间
-		// 由于该时间点基于系统启动时间开始计算, 所以无法格式化该时间, 
-		// 也无法获得该时间的 Unix 时间戳
-		static Time Now() noexcept;
-
 	private:
 		Time(long ms);
 

src/kiwano/platform/Application.cpp

@@ -262,10 +262,10 @@ namespace kiwano
 		}
 	}
 
-	void Application::PreformInMainThread(Function<void()> Function)
+	void Application::PreformInMainThread(Function<void()> func)
 	{
 		std::lock_guard<std::mutex> lock(perform_mutex_);
-		functions_to_perform_.push(Function);
+		functions_to_perform_.push(func);
 	}
 
 	LRESULT CALLBACK Application::WndProc(HWND hwnd, UINT32 msg, WPARAM wparam, LPARAM lparam)

src/kiwano/platform/Application.h

@@ -28,19 +28,36 @@
 
 namespace kiwano
 {
+	/**
+	* \~chinese
+	* @brief 应用程序配置
+	* @details 启动 Kiwano 应用程序前的初始化选项
+	*/
 	struct Config
 	{
-		WindowConfig window;	// 窗口设置
-		RenderConfig render;	// 渲染设置
-		bool debug;				// 调试模式
+		WindowConfig window;	///< 窗口配置
+		RenderConfig render;	///< 渲染配置
+		bool debug;				///< 启用调试模式
 
+		/**
+		* \~chinese
+		* @param title 窗口标题
+		* @param width 窗口宽度
+		* @param height 窗口高度
+		* @param icon 窗口图标的资源ID
+		*/
 		Config(
-			String const& title		= L"Kiwano Game",
+			String const& title	= L"Kiwano Game",
 			uint32_t width		= 640,
-			uint32_t height	= 480,
+			uint32_t height		= 480,
 			uint32_t icon		= 0
 		);
 
+		/**
+		* \~chinese
+		* @param wnd_config 窗口配置
+		* @param render_config 渲染配置
+		*/
 		Config(
 			WindowConfig const& wnd_config,
 			RenderConfig const& render_config = RenderConfig()
@@ -48,7 +65,10 @@ namespace kiwano
 	};
 
 
-	// 应用
+	/**
+	* \~chinese
+	* @brief 应用程序，控制游戏的整个生命周期，包括初始化、启动、结束以及事件分发等
+	*/
 	class KGE_API Application
 		: protected Noncopyable
 	{
@@ -57,46 +77,94 @@ namespace kiwano
 
 		virtual ~Application();
 
-		// 初始化
+		/**
+		* \~chinese
+		* @brief 初始化应用程序
+		* @details 初始化所有功能组件后执行 OnReady 函数
+		* @param config 初始化配置
+		* @attention 应在使用其他功能前执行初始化，否则可能引发异常
+		*/
 		void Init(
 			Config const& config = Config()
 		);
 
-		// 初始化成功时
+		/**
+		* \~chinese
+		* @brief 初始化完成处理
+		* @details 重载该函数以在应用程序初始化完成后自动执行
+		*/
 		virtual void OnReady() {}
 
-		// 窗口关闭时
+		/**
+		* \~chinese
+		* @brief 窗口关闭处理
+		* @details 重载该函数以处理用户关闭应用程序窗口时的行为
+		* @return 返回 true 则正常关闭窗口，否则阻止窗口关闭
+		*/
 		virtual bool OnClosing() { return true; }
 
-		// 销毁时
+		/**
+		* \~chinese
+		* @brief 应用程序销毁处理
+		* @details 重载该函数以处理应用程序销毁时的行为，如完成资源回收等
+		*/
 		virtual void OnDestroy() {}
 
-		// 运行
+		/**
+		* \~chinese
+		* @brief 启动应用程序
+		* @note 该函数是阻塞的，应用程序结束时函数返回
+		*/
 		void Run();
 
-		// 结束
+		/**
+		* \~chinese
+		* @brief 终止应用程序
+		*/
 		void Quit();
 
-		// 销毁
+		/**
+		* \~chinese
+		* @brief 销毁游戏运行过程中产生的所有资源
+		*/
 		void Destroy();
 
-		// 添加组件
+		/**
+		* \~chinese
+		* @brief 添加功能组件
+		* @param[in] component 功能组件
+		*/
 		void Use(
 			ComponentBase* component
 		);
 
-		// 设置时间缩放因子
+		/**
+		* \~chinese
+		* @brief 设置时间缩放因子
+		* @details 设置时间缩放因子可等比例放大或缩小时间进度
+		* @param scale_factor 缩放因子
+		* @warning 设置为负数可能导致动画系统紊乱
+		*/
 		void SetTimeScale(
 			float scale_factor
 		);
 
-		// 分发事件
+		/**
+		* \~chinese
+		* @brief 分发事件
+		* @details 将事件分发给所有事件功能组件
+		* @param evt 事件
+		*/
 		void DispatchEvent(Event& evt);
 
-		// 在 Kiwano 主线程中执行函数
-		// 当在其他线程调用 Kiwano 函数时使用
+		/**
+		* \~chinese
+		* @brief 在主线程中执行函数
+		* @details 提供在其他线程调用 Kiwano 函数的能力
+		* @param func 需要执行的函数
+		*/
 		static void PreformInMainThread(
-			Function<void()> Function
+			Function<void()> func
 		);
 
 	protected:

src/kiwano/platform/Director.h

@@ -24,43 +24,75 @@
 
 namespace kiwano
 {
-	// 导演
+	/**
+	* \~chinese
+	* @brief 导演完成场景的渲染、更新、事件分发以及控制场景间跳转
+	*/
 	class KGE_API Director
 		: public Singleton<Director>
 		, public UpdateComponent
 		, public RenderComponent
 		, public EventComponent
 	{
-		OC_DECLARE_SINGLETON(Director);
+		friend Singleton<Director>;
 
 	public:
-		// 切换舞台
+		/**
+		* \~chinese
+		* @brief 切换舞台
+		* @param[in] stage 舞台
+		* @param[in] transition 过渡动画
+		*/
 		void EnterStage(
-			StagePtr stage,						/* 舞台 */
-			TransitionPtr transition = nullptr	/* 过渡动画 */
+			StagePtr stage,
+			TransitionPtr transition = nullptr
 		);
 
-		// 舞台压栈
+		/**
+		* \~chinese
+		* @brief 切换舞台，并将当前舞台压栈
+		* @param[in] stage 舞台
+		* @param[in] transition 过渡动画
+		*/
 		void PushStage(
-			StagePtr stage,						/* 舞台 */
-			TransitionPtr transition = nullptr	/* 过渡动画 */
+			StagePtr stage,
+			TransitionPtr transition = nullptr
 		);
 
-		// 舞台出栈
+		/**
+		* \~chinese
+		* @brief 退出当前舞台，并切换到栈顶舞台
+		* @param[in] transition 过渡动画
+		*/
 		void PopStage(
-			TransitionPtr transition = nullptr	/* 过渡动画 */
+			TransitionPtr transition = nullptr
 		);
 
-		// 获取当前舞台
+		/**
+		* \~chinese
+		* @brief 获取当前舞台
+		* @return 返回当前舞台的指针
+		*/
 		StagePtr GetCurrentStage();
 
-		// 启用或禁用角色边界渲染功能
+		/**
+		* \~chinese
+		* @brief 启用或禁用角色边界渲染功能
+		* @param enabled 是否启用
+		*/
 		void SetRenderBorderEnabled(bool enabled);
 
-		// 显示调试信息
+		/**
+		* \~chinese
+		* @brief 显示或隐藏调试信息
+		* @param show 是否显示
+		*/
 		void ShowDebugInfo(bool show = true);
 
-		// 清空舞台
+		/**
+		* \~chinese
+		* @brief 退出当前舞台并清空舞台栈
+		*/
 		void ClearStages();
 
 	public:

src/kiwano/platform/FileSystem.h

@@ -23,41 +23,87 @@
 
 namespace kiwano
 {
-    // 文件
+	/**
+	* \~chinese
+	* @brief 文件系统，为其他模块提供文件搜索规则等
+	*/
 	class KGE_API FileSystem
 		: public Singleton<FileSystem>
 	{
-		OC_DECLARE_SINGLETON(FileSystem);
+		friend Singleton<FileSystem>;
 
 	public:
-		// 添加文件搜索路径
+		/**
+		* \~chinese
+		* @brief 添加文件搜索路径
+		* @param path 文件搜索路径
+		*/
 		void AddSearchPath(String const& path);
 
-		// 设置文件搜索路径
+		/**
+		* \~chinese
+		* @brief 设置文件搜索路径
+		* @param paths 搜索路径数组
+		*/
 		void SetSearchPaths(Vector<String> const& paths);
 
-		// 获取文件的完整路径
+		/**
+		* \~chinese
+		* @brief 在搜索列表中查找文件并获取完整路径
+		* @param file 文件路径
+		* @return 完整的文件路径
+		*/
 		String GetFullPathForFile(String const& file) const;
 
-		// 添加文件路径查找字典规则
+		/**
+		* \~chinese
+		* @brief 添加文件路径查找字典规则
+		* @param key 文件关键词
+		* @param file_path 文件路径
+		*/
 		void AddFileLookupRule(String const& key, String const& file_path);
 
-		// 设置文件路径查找字典
+		/**
+		* \~chinese
+		* @brief 设置文件路径查找字典
+		* @param dict 文件路径查找字典
+		*/
 		void SetFileLookupDictionary(UnorderedMap<String, String> const& dict);
 
-		// 文件是否存在
+		/**
+		* \~chinese
+		* @brief 文件是否存在
+		* @param file_path 文件路径
+		* @return 若文件存在，返回 true
+		*/
 		bool IsFileExists(String const& file_path) const;
 
-		// 判断路径是否是绝对路径
+		/**
+		* \~chinese
+		* @brief 判断路径是否是绝对路径
+		* @param path 文件路径
+		* @return 若是绝对路径，返回 true
+		*/
 		bool IsAbsolutePath(String const& path) const;
 
-		// 删除文件
+		/**
+		* \~chinese
+		* @brief 删除文件
+		* @param path 文件路径
+		* @return 删除是否成功
+		*/
 		bool RemoveFile(String const& file_path) const;
 
-		// 释放二进制资源到临时文件目录
+		/**
+		* \~chinese
+		* @brief 释放二进制资源到临时文件目录
+		* @param res 资源
+		* @param dest_file_name 目标文件名
+		* @return 操作是否成功
+		*/
 		bool ExtractResourceToFile(
-			Resource const& res,			/* 资源 */
-			String const& dest_file_name	/* 目标文件名 */
+			Resource const& res,
+			String const& dest_file_name
 		) const;
 
 	private:

src/kiwano/platform/Input.h

@@ -27,36 +27,70 @@
 
 namespace kiwano
 {
+	/**
+	* \~chinese
+	* @brief 输入设备实例，可获取鼠标和键盘的按键状态
+	*/
 	class KGE_API Input
 		: public Singleton<Input>
 		, public UpdateComponent
 		, public EventComponent
 	{
-		OC_DECLARE_SINGLETON(Input);
+		friend Singleton<Input>;
 
 	public:
-		// 检测键盘或鼠标按键是否正被按下
+		/**
+		* \~chinese
+		* @brief 检测键盘或鼠标按键是否正被按下
+		* @param key_or_btn 键值
+		* @return 是否正被按下
+		* @see kiwano::KeyCode kiwano::MouseButton
+		*/
 		bool IsDown(
 			int key_or_btn
 		);
 
-		// 检测键盘或鼠标按键是否刚被点击
+		/**
+		* \~chinese
+		* @brief 检测键盘或鼠标按键是否刚被点击
+		* @param key_or_btn 键值
+		* @return 是否刚被点击
+		* @see kiwano::KeyCode kiwano::MouseButton
+		*/
 		bool WasPressed(
 			int key_or_btn
 		);
 
-		// 检测键盘或鼠标按键是否刚抬起
+		/**
+		* \~chinese
+		* @brief 检测键盘或鼠标按键是否刚抬起
+		* @param key_or_btn 键值
+		* @return 是否刚抬起
+		* @see kiwano::KeyCode kiwano::MouseButton
+		*/
 		bool WasReleased(
 			int key_or_btn
 		);
 
-		// 获得鼠标 x 坐标
+		/**
+		* \~chinese
+		* @brief 获得鼠标 x 坐标
+		* @return 鼠标 x 坐标
+		*/
 		float GetMouseX();
 
-		// 获得鼠标 y 坐标
+		/**
+		* \~chinese
+		* @brief 获得鼠标 y 坐标
+		* @return 鼠标 y 坐标
+		*/
 		float GetMouseY();
 
-		// 获得鼠标坐标
+		/**
+		* \~chinese
+		* @brief 获得鼠标坐标
+		* @return 鼠标坐标
+		*/
 		Point GetMousePos();
 
 	public:

src/kiwano/platform/Window.h

@@ -25,29 +25,45 @@
 
 namespace kiwano
 {
-	// 鼠标指针类型
+	/**
+	* \~chinese
+	* @brief 鼠标指针类型
+	*/
 	enum class CursorType
 	{
-		Arrow,		/* 指针 */
-		TextInput,	/* 文本 */
-		Hand,		/* 手指 */
-		SizeAll,
-		SizeNESW,
-		SizeNS,
-		SizeNWSE,
-		SizeWE,
+		Arrow,		///< 指针
+		TextInput,	///< 文本
+		Hand,		///< 手
+		SizeAll,	///< 指向四个方向的箭头
+		SizeWE,		///< 指向左右方向的箭头
+		SizeNS,		///< 指向上下方向的箭头
+		SizeNESW,	///< 指向左下到右上方向的箭头
+		SizeNWSE,	///< 指向左上到右下方向的箭头
 	};
 
-	// 窗口设置
+	/**
+	* \~chinese
+	* @brief 窗口设置
+	*/
 	struct WindowConfig
 	{
-		String		title;				// 标题
-		uint32_t	width;				// 宽度
-		uint32_t	height;				// 高度
-		uint32_t	icon;				// 图标资源 ID
-		bool		resizable;			// 窗口大小可拉伸
-		bool		fullscreen;			// 全屏模式
+		String		title;			///< 标题
+		uint32_t	width;			///< 宽度
+		uint32_t	height;			///< 高度
+		uint32_t	icon;			///< 图标资源 ID
+		bool		resizable;		///< 窗口大小可拉伸
+		bool		fullscreen;		///< 全屏模式
 
+		/**
+		* \~chinese
+		* @brief 构建窗口设置
+		* @param title 标题
+		* @param width 宽度
+		* @param height 高度
+		* @param icon 图标资源ID
+		* @param resizable 窗口大小可拉伸
+		* @param fullscreen 全屏模式
+		*/
 		WindowConfig(
 			String const&	title = L"Kiwano Game",
 			uint32_t		width = 640,
@@ -59,38 +75,80 @@ namespace kiwano
 	};
 
 
-	// 窗口
+	/**
+	* \~chinese
+	* @brief 窗口实例，控制窗口标题、大小、图标等
+	*/
 	class KGE_API Window
 		: public Singleton<Window>
 	{
-		OC_DECLARE_SINGLETON(Window);
+		friend Singleton<Window>;
 
 	public:
-		// 获取标题
+		/**
+		* \~chinese
+		* @brief 获取窗口标题
+		* @return 窗口标题
+		*/
 		String GetTitle() const;
 
-		// 获取窗口大小
+		/**
+		* \~chinese
+		* @brief 获取窗口大小
+		* @return 窗口大小
+		*/
 		Size GetSize() const;
 
-		// 获取窗口宽度
+		/**
+		* \~chinese
+		* @brief 获取窗口宽度
+		* @return 窗口宽度
+		*/
 		float GetWidth() const;
 
-		// 获取窗口高度
+		/**
+		* \~chinese
+		* @brief 获取窗口高度
+		* @return 窗口高度
+		*/
 		float GetHeight() const;
 
-		// 设置标题
+		/**
+		* \~chinese
+		* @brief 设置标题
+		* @param title 标题
+		*/
 		void SetTitle(String const& title);
 
-		// 设置窗口图标
+		/**
+		* \~chinese
+		* @brief 设置窗口图标
+		* @param icon_resource 图标资源ID
+		*/
 		void SetIcon(uint32_t icon_resource);
 
-		// 重设窗口大小
+		/**
+		* \~chinese
+		* @brief 重设窗口大小
+		* @param width 窗口宽度
+		* @param height 窗口高度
+		*/
 		void Resize(int width, int height);
 
-		// 设置全屏模式
+		/**
+		* \~chinese
+		* @brief 设置全屏模式
+		* @param fullscreen 是否全屏
+		* @param width 窗口宽度
+		* @param height 窗口高度
+		*/
 		void SetFullscreen(bool fullscreen, int width, int height);
 
-		// 设置鼠标指针类型
+		/**
+		* \~chinese
+		* @brief 设置鼠标指针类型
+		* @param cursor 鼠标指针类型
+		*/
 		void SetCursor(CursorType cursor);
 
 	public:

src/kiwano/renderer/Renderer.h

@@ -59,7 +59,7 @@ namespace kiwano
 		, public EventComponent
 		, public RenderTarget
 	{
-		OC_DECLARE_SINGLETON(Renderer);
+		friend Singleton<Renderer>;
 
 	public:
 		// <20>零헌팁奈<ED8C81>

src/kiwano/renderer/TextureCache.h

@@ -27,7 +27,7 @@ namespace kiwano
 	class KGE_API TextureCache
 		: public Singleton<TextureCache>
 	{
-		OC_DECLARE_SINGLETON(TextureCache);
+		friend Singleton<TextureCache>;
 
 	public:
 		Texture AddOrGetTexture(String const& file_path);

src/kiwano/utils/ResourceCache.h

@@ -30,7 +30,7 @@ namespace kiwano
 	class KGE_API ResourceCache
 		: public Singleton<ResourceCache>
 	{
-		OC_DECLARE_SINGLETON(ResourceCache);
+		friend Singleton<ResourceCache>;
 
 	public:
 		// 从 JSON 文件加载资源信息

src/kiwano/utils/UserData.h

@@ -27,7 +27,7 @@ namespace kiwano
 	class KGE_API UserData
 		: public Singleton<UserData>
 	{
-		OC_DECLARE_SINGLETON(UserData);
+		friend Singleton<UserData>;
 
 	public:
 		using DataMap = UnorderedMap<String, Any>;