docs: update core and debug API docs
This commit is contained in:
@@ -4,6 +4,8 @@
|
||||
|
||||
**类型**: `module`
|
||||
|
||||
**头文件**: `XCEngine/Core/Core.h`
|
||||
|
||||
**描述**: XCEngine 的核心基础模块，提供类型别名、智能指针、事件系统等基础功能。
|
||||
|
||||
## 概述
|
||||
|
||||
@@ -4,6 +4,8 @@
|
||||
|
||||
**类型**: `class` (template)
|
||||
|
||||
**头文件**: `XCEngine/Core/Event.h`
|
||||
|
||||
**描述**: 事件系统模板类，提供类型安全的多订阅者事件/委托系统。
|
||||
|
||||
## 概述
|
||||
|
||||
@@ -10,6 +10,10 @@ void Close();
|
||||
|
||||
关闭当前打开的文件。如果文件未打开，则什么都不做。析构函数会自动调用此方法。
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**线程安全：** ❌
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
@@ -12,6 +12,8 @@ bool Flush();
|
||||
|
||||
**返回：** `bool` - 是否刷新成功
|
||||
|
||||
**线程安全：** ❌
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
@@ -12,6 +12,8 @@ bool IsOpen() const;
|
||||
|
||||
**返回：** `bool` - 文件是否已打开
|
||||
|
||||
**线程安全：** ✅
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
@@ -16,6 +16,8 @@ bool Open(const char* filePath, bool append = false);
|
||||
|
||||
**返回：** `bool` - 是否成功打开
|
||||
|
||||
**线程安全：** ❌
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
@@ -18,6 +18,8 @@ bool Write(const Containers::String& str);
|
||||
|
||||
**返回：** `bool` - 是否写入成功
|
||||
|
||||
**线程安全：** ❌
|
||||
|
||||
**复杂度：** O(n) 其中 n 为写入的字节数
|
||||
|
||||
**示例：**
|
||||
|
||||
36
docs/api/core/filewriter/ctor-default.md
Normal file
36
docs/api/core/filewriter/ctor-default.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# FileWriter::FileWriter (默认构造)
|
||||
|
||||
```cpp
|
||||
FileWriter();
|
||||
```
|
||||
|
||||
默认构造 FileWriter 对象，不打开任何文件。
|
||||
|
||||
**描述**
|
||||
|
||||
创建 FileWriter 实例，m_file 初始化为 nullptr。可后续通过 Open 方法打开文件。
|
||||
|
||||
**线程安全：** ❌
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Core/FileWriter.h>
|
||||
|
||||
using namespace XCEngine::Core;
|
||||
|
||||
FileWriter writer;
|
||||
if (!writer.IsOpen()) {
|
||||
writer.Open("output.txt");
|
||||
writer.Write("Hello\n");
|
||||
writer.Close();
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [FileWriter 总览](filewriter.md) - 返回类总览
|
||||
- [Open](Open.md) - 打开文件
|
||||
- [FileWriter(filePath, append)](ctor-file.md) - 构造并打开文件
|
||||
45
docs/api/core/filewriter/ctor-file.md
Normal file
45
docs/api/core/filewriter/ctor-file.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# FileWriter::FileWriter (文件路径构造)
|
||||
|
||||
```cpp
|
||||
FileWriter(const char* filePath, bool append = false);
|
||||
```
|
||||
|
||||
构造 FileWriter 对象并打开文件。
|
||||
|
||||
**描述**
|
||||
|
||||
创建 FileWriter 实例并尝试打开指定路径的文件。如果 append 为 true，则以追加模式打开；否则以覆盖模式打开。
|
||||
|
||||
**参数：**
|
||||
- `filePath` - 要打开的文件路径
|
||||
- `append` - 是否以追加模式打开，默认 false（覆盖模式）
|
||||
|
||||
**线程安全：** ❌
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Core/FileWriter.h>
|
||||
|
||||
using namespace XCEngine::Core;
|
||||
|
||||
// 覆盖模式打开
|
||||
FileWriter writer1("output.txt");
|
||||
if (writer1.IsOpen()) {
|
||||
writer1.Write("Content\n");
|
||||
}
|
||||
|
||||
// 追加模式打开
|
||||
FileWriter writer2("log.txt", true);
|
||||
if (writer2.IsOpen()) {
|
||||
writer2.Write("New log entry\n");
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [FileWriter 总览](filewriter.md) - 返回类总览
|
||||
- [Open](Open.md) - 打开文件
|
||||
- [FileWriter()](ctor-default.md) - 默认构造
|
||||
33
docs/api/core/filewriter/dtor.md
Normal file
33
docs/api/core/filewriter/dtor.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# FileWriter::~FileWriter
|
||||
|
||||
```cpp
|
||||
~FileWriter();
|
||||
```
|
||||
|
||||
析构函数，自动关闭文件。
|
||||
|
||||
**描述**
|
||||
|
||||
销毁 FileWriter 实例，如果文件处于打开状态则自动调用 Close 关闭文件，释放 FILE* 资源。
|
||||
|
||||
**线程安全：** ❌
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Core/FileWriter.h>
|
||||
|
||||
using namespace XCEngine::Core;
|
||||
|
||||
{
|
||||
FileWriter writer("output.txt");
|
||||
writer.Write("Content inside scope\n");
|
||||
} // 析构时自动关闭文件
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [FileWriter 总览](filewriter.md) - 返回类总览
|
||||
- [Close](Close.md) - 关闭文件
|
||||
@@ -4,6 +4,8 @@
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**头文件**: `XCEngine/Core/FileWriter.h`
|
||||
|
||||
**描述**: 文件写入工具类，提供简单的文件写入操作封装。
|
||||
|
||||
## 概述
|
||||
@@ -14,9 +16,9 @@
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `FileWriter()` | 默认构造（不打开文件） |
|
||||
| `FileWriter(const char* filePath, bool append = false)` | 构造并打开文件 |
|
||||
| `~FileWriter()` | 析构函数，自动关闭文件 |
|
||||
| [`FileWriter()`](ctor-default.md) | 默认构造（不打开文件） |
|
||||
| [`FileWriter(filePath, append)`](ctor-file.md) | 构造并打开文件 |
|
||||
| [`~FileWriter()`](dtor.md) | 析构函数，自动关闭文件 |
|
||||
| [`Open`](Open.md) | 打开文件，append=true 时为追加模式 |
|
||||
| [`Close`](Close.md) | 关闭文件 |
|
||||
| [`IsOpen`](IsOpen.md) | 检查文件是否已打开 |
|
||||
|
||||
@@ -4,34 +4,40 @@
|
||||
void AddRef();
|
||||
```
|
||||
|
||||
增加引用计数。
|
||||
原子地增加引用计数。
|
||||
|
||||
**描述**
|
||||
|
||||
原子地增加引用计数。在复制 `RefCounted` 指针或传递引用时调用此方法。
|
||||
|
||||
**线程安全：** ✅
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Core/RefCounted.h>
|
||||
#include <cstdio>
|
||||
|
||||
class MyObject : public RefCounted {
|
||||
class MyObject : public XCEngine::Core::RefCounted {
|
||||
public:
|
||||
void DoSomething() { /* ... */ }
|
||||
void DoSomething() { }
|
||||
};
|
||||
|
||||
// 创建对象（构造时 refCount = 1）
|
||||
MyObject* obj = new MyObject();
|
||||
|
||||
// 手动增加引用
|
||||
obj->AddRef(); // refCount = 2
|
||||
obj->AddRef(); // refCount = 3
|
||||
|
||||
// 需要释放额外的引用
|
||||
obj->Release(); // refCount = 2
|
||||
obj->Release(); // refCount = 1
|
||||
int main() {
|
||||
MyObject* obj = new MyObject();
|
||||
printf("After create: %u\n", obj->GetRefCount());
|
||||
|
||||
obj->AddRef();
|
||||
printf("After AddRef: %u\n", obj->GetRefCount());
|
||||
|
||||
obj->Release();
|
||||
printf("After Release: %u\n", obj->GetRefCount());
|
||||
|
||||
obj->Release();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
@@ -12,28 +12,36 @@ uint32_t GetRefCount() const;
|
||||
|
||||
**返回：** `uint32_t` - 当前引用计数
|
||||
|
||||
**线程安全：** ✅
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Core/RefCounted.h>
|
||||
#include <cstdio>
|
||||
|
||||
class MyObject : public RefCounted {
|
||||
class MyObject : public XCEngine::Core::RefCounted {
|
||||
public:
|
||||
void Debug() {
|
||||
printf("RefCount: %u\n", GetRefCount());
|
||||
}
|
||||
};
|
||||
|
||||
MyObject* obj = new MyObject();
|
||||
printf("After create: %u\n", obj->GetRefCount()); // 1
|
||||
|
||||
obj->AddRef();
|
||||
printf("After AddRef: %u\n", obj->GetRefCount()); // 2
|
||||
|
||||
obj->Release();
|
||||
printf("After Release: %u\n", obj->GetRefCount()); // 1
|
||||
int main() {
|
||||
MyObject* obj = new MyObject();
|
||||
printf("After create: %u\n", obj->GetRefCount());
|
||||
|
||||
obj->AddRef();
|
||||
printf("After AddRef: %u\n", obj->GetRefCount());
|
||||
|
||||
obj->Release();
|
||||
printf("After Release: %u\n", obj->GetRefCount());
|
||||
|
||||
obj->Release();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
@@ -4,33 +4,40 @@
|
||||
void Release();
|
||||
```
|
||||
|
||||
减少引用计数。
|
||||
原子地减少引用计数。
|
||||
|
||||
**描述**
|
||||
|
||||
原子地减少引用计数。当引用计数归零时，对象会自动 `delete this`。这是实现自动内存管理的关键方法。
|
||||
|
||||
**复杂度：** O(1)（归零时为 O(n)，n 为对象大小）
|
||||
**线程安全：** ✅
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Core/RefCounted.h>
|
||||
#include <cstdio>
|
||||
|
||||
class MyObject : public RefCounted {
|
||||
class MyObject : public XCEngine::Core::RefCounted {
|
||||
public:
|
||||
void DoSomething() { /* ... */ }
|
||||
void DoSomething() { }
|
||||
};
|
||||
|
||||
// 创建对象（构造时 refCount = 1）
|
||||
MyObject* obj = new MyObject();
|
||||
|
||||
// 手动增加引用
|
||||
obj->AddRef(); // refCount = 2
|
||||
|
||||
// 释放引用
|
||||
obj->Release(); // refCount = 1
|
||||
obj->Release(); // refCount = 0, 对象被自动 delete
|
||||
int main() {
|
||||
MyObject* obj = new MyObject();
|
||||
printf("After create: %u\n", obj->GetRefCount());
|
||||
|
||||
obj->AddRef();
|
||||
printf("After AddRef: %u\n", obj->GetRefCount());
|
||||
|
||||
obj->Release();
|
||||
printf("After Release: %u\n", obj->GetRefCount());
|
||||
|
||||
obj->Release();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
@@ -4,6 +4,8 @@
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**头文件**: `XCEngine/Core/RefCounted.h`
|
||||
|
||||
**描述**: 引用计数基类，提供线程安全的引用计数生命周期管理。
|
||||
|
||||
## 概述
|
||||
@@ -14,28 +16,39 @@
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `RefCounted()` | 构造函数，初始引用计数为 1 |
|
||||
| `virtual ~RefCounted()` | 虚析构函数 |
|
||||
| [`AddRef`](AddRef.md) | 增加引用计数 |
|
||||
| [`Release`](Release.md) | 减少引用计数（归零时自动 delete this） |
|
||||
| [`GetRefCount`](GetRefCount.md) | 获取当前引用计数 |
|
||||
| [`RefCounted()`](refcounted.md) | 构造函数，初始引用计数为 1 |
|
||||
| [`~RefCounted()`](refcounted.md) | 虚析构函数 |
|
||||
| [`AddRef()`](AddRef.md) | 增加引用计数 |
|
||||
| [`Release()`](Release.md) | 减少引用计数（归零时自动 delete this） |
|
||||
| [`GetRefCount()`](GetRefCount.md) | 获取当前引用计数 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
class MyObject : public RefCounted {
|
||||
#include <XCEngine/Core/RefCounted.h>
|
||||
#include <cstdio>
|
||||
|
||||
class MyObject : public XCEngine::Core::RefCounted {
|
||||
public:
|
||||
MyObject() { /* ... */ }
|
||||
~MyObject() { /* ... */ }
|
||||
MyObject() { }
|
||||
virtual ~MyObject() { }
|
||||
|
||||
void DoSomething() { /* ... */ }
|
||||
void DoSomething() { }
|
||||
};
|
||||
|
||||
// 使用
|
||||
MyObject* obj = new MyObject(); // refCount = 1
|
||||
obj->AddRef(); // refCount = 2
|
||||
obj->Release(); // refCount = 1
|
||||
obj->Release(); // refCount = 0, 自动 delete
|
||||
int main() {
|
||||
MyObject* obj = new MyObject();
|
||||
printf("After create: %u\n", obj->GetRefCount());
|
||||
|
||||
obj->AddRef();
|
||||
printf("After AddRef: %u\n", obj->GetRefCount());
|
||||
|
||||
obj->Release();
|
||||
printf("After Release: %u\n", obj->GetRefCount());
|
||||
|
||||
obj->Release();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
@@ -4,6 +4,8 @@
|
||||
|
||||
**类型**: `header-only`
|
||||
|
||||
**头文件**: `XCEngine/Core/SmartPtr.h`
|
||||
|
||||
**描述**: 智能指针类型别名和工厂函数，提供 `std::shared_ptr` 和 `std::unique_ptr` 的简化接口。
|
||||
|
||||
## 概述
|
||||
|
||||
@@ -10,8 +10,6 @@ using byte = uint8_t;
|
||||
|
||||
`byte` 是 1 字节无符号整数类型，专门用于表示原始字节数据。语义上比 `uint8` 更清晰，适用于二进制数据、内存缓冲区等场景。
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
|
||||
@@ -10,8 +10,6 @@ using int16 = int16_t;
|
||||
|
||||
`int16` 是 16 位（2 字节）有符号整数类型，范围为 -32,768 到 32,767。该类型别名确保跨平台一致性。
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
|
||||
@@ -10,8 +10,6 @@ using int32 = int32_t;
|
||||
|
||||
`int32` 是 32 位（4 字节）有符号整数类型，范围为 -2,147,483,648 到 2,147,483,647。该类型别名确保跨平台一致性，是最常用的整数类型。
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
|
||||
@@ -10,8 +10,6 @@ using int64 = int64_t;
|
||||
|
||||
`int64` 是 64 位（8 字节）有符号整数类型，范围为 -9,223,372,036,854,775,808 到 9,223,372,036,854,775,807。该类型别名用于需要大范围整数的场景，如时间戳、大文件大小等。
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
|
||||
@@ -10,8 +10,6 @@ using int8 = int8_t;
|
||||
|
||||
`int8` 是 8 位（1 字节）有符号整数类型，范围为 -128 到 127。该类型别名确保跨平台一致性。
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
**命名空间**: `XCEngine::Core`
|
||||
|
||||
**类型**: `header` (type aliases)
|
||||
**类型**: `类型别名定义`
|
||||
|
||||
**头文件**: `XCEngine/Core/Types.h`
|
||||
|
||||
@@ -26,9 +26,9 @@
|
||||
| `uint64` | `uint64_t` | 64位无符号整数 |
|
||||
| `byte` | `uint8_t` | 字节类型 |
|
||||
|
||||
## 公共方法
|
||||
## 类型定义
|
||||
|
||||
| 方法 | 描述 |
|
||||
| 类型 | 描述 |
|
||||
|------|------|
|
||||
| [`int8`](int8.md) | 8位有符号整数类型别名 |
|
||||
| [`int16`](int16.md) | 16位有符号整数类型别名 |
|
||||
@@ -59,5 +59,4 @@ void ProcessData(Core::uint32 size, const Core::int8* data);
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Core 模块总览](../core.md) - 返回模块总览
|
||||
- [SmartPtr](../smartptr/smartptr.md) - 智能指针
|
||||
- [SmartPtr](../smartptr/smartptr.md) - 智能指针（该文档暂缺）
|
||||
|
||||
@@ -10,8 +10,6 @@ using uint16 = uint16_t;
|
||||
|
||||
`uint16` 是 16 位（2 字节）无符号整数类型，范围为 0 到 65,535。常用于 Unicode 字符、端口号等场景。
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
|
||||
@@ -10,8 +10,6 @@ using uint32 = uint32_t;
|
||||
|
||||
`uint32` 是 32 位（4 字节）无符号整数类型，范围为 0 到 4,294,967,295。常用于 ID、计数、大小等场景。
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
|
||||
@@ -10,8 +10,6 @@ using uint64 = uint64_t;
|
||||
|
||||
`uint64` 是 64 位（8 字节）无符号整数类型，范围为 0 到 18,446,744,073,709,551,615。用于需要极大整数范围的场景，如大文件大小、精确时间等。
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
|
||||
@@ -10,8 +10,6 @@ using uint8 = uint8_t;
|
||||
|
||||
`uint8` 是 8 位（1 字节）无符号整数类型，范围为 0 到 255。常用于字节数据、颜色分量（RGB）等场景。
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
|
||||
Reference in New Issue
Block a user