chore: update version to 1.0.2 and enhance documentationv1.0.2

5 files changed, 112 insertions, 363 deletions

diff --git a/Cargo.toml b/Cargo.toml
index 2e4f8e7..f1d9018 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "oneroll"
-version = "1.0.1"
+version = "1.0.2"
 edition = "2021"
 description = "A Pyo3 Project Template For HydroRoll."
 license = "AGPL-3.0"
diff --git a/README.rst b/README.rst
index c764c79..868d783 100644
--- a/README.rst
+++ b/README.rst
@@ -1,4 +1,113 @@
 OneRoll
 =======
 
-    An efficient dice expression parsing tool, based on Rust and PEG grammar
\ No newline at end of file
+An efficient dice expression parsing tool, based on Rust and PEG grammar.
+
+Overview
+--------
+
+OneRoll is a high-performance dice expression parser and roller, implemented in Rust and exposed to Python via PyO3. It supports complex dice expressions, modifiers, mathematical operations, and user comments.
+
+Features
+--------
+
+- Basic dice rolling (XdY)
+- Mathematical operations: +, -, *, /, ^
+- Modifiers: !, kh, kl, dh, dl, r, ro
+- Bracket support
+- User comments (e.g., `3d6 + 2 # Attack roll`)
+- Complete error handling
+- Statistical rolling and analysis
+- Rich terminal UI (TUI) via `textual`
+- Python SDK and CLI
+
+Installation
+------------
+
+.. code-block:: shell
+
+   pip install oneroll
+
+Or build from source:
+
+.. code-block:: shell
+
+   maturin build
+   pip install target/wheels/oneroll-*.whl
+
+Usage
+-----
+
+Python SDK Example:
+
+.. code-block:: python
+
+   import oneroll
+
+   # Basic roll
+   result = oneroll.roll("3d6 + 2")
+   print(result["total"])
+
+   # With comment
+   result = oneroll.roll("4d6kh3 # Attribute roll")
+   print(result["comment"])
+
+   # Use OneRoll class
+   roller = oneroll.OneRoll()
+   result = roller.roll("2d6! # Exploding dice")
+
+Command Line Example:
+
+.. code-block:: shell
+
+   python -m oneroll "3d6 + 2"
+   python -m oneroll --stats "3d6" --times 100
+
+Terminal UI:
+
+.. code-block:: shell
+
+   python -m oneroll.tui
+
+Dice Expression Syntax
+----------------------
+
+- `XdY`: Roll X dice with Y sides
+- Modifiers: `kh`, `kl`, `dh`, `dl`, `!`, `r`, `ro`
+- Mathematical operations: `+`, `-`, `*`, `/`, `^`
+- Comments: Add with `#`, e.g., `3d6 + 2 # Attack roll`
+
+Examples
+--------
+
+.. code-block:: python
+
+   # Basic
+   result = oneroll.roll("3d6 + 2")
+
+   # D&D attribute roll
+   result = oneroll.roll("4d6kh3 # Attribute")
+
+   # Statistical analysis
+   stats = oneroll.roll_statistics("3d6", 100)
+
+   # Comment usage
+   result = oneroll.roll("1d20 + 5 # Attack check")
+   print(result["comment"])
+
+Documentation
+-------------
+
+- Homepage: https://hydroroll.team/
+- Repository: https://github.com/HydroRoll-Team/oneroll
+- Docs: https://oneroll.hydroroll.team/
+
+License
+-------
+
+AGPL-3.0
+
+Authors
+-------
+
+HsiangNianian <leader@hydroroll.team>
\ No newline at end of file
diff --git a/examples/comment_example.py b/examples/comment_example.py
deleted file mode 100644
index e7242cb..0000000
--- a/examples/comment_example.py
+++ /dev/null
@@ -1,195 +0,0 @@
-#!/usr/bin/env python3
-"""
-OneRoll 注释功能示例
-
-展示如何使用 OneRoll 的注释功能来标记和记录骰子投掷。
-"""
-
-import oneroll
-from rich.console import Console
-from rich.table import Table
-from rich.panel import Panel
-
-console = Console()
-
-def basic_comment_example():
-    """基本注释功能示例"""
-    console.print(Panel.fit("基本注释功能示例", style="bold blue"))
-    
-    # 基本注释
-    result = oneroll.roll("3d6 + 2 # 攻击投掷")
-    console.print(f"表达式: {result['expression']}")
-    console.print(f"总点数: {result['total']}")
-    console.print(f"注释: {result['comment']}")
-    console.print()
-
-def dnd_comment_example():
-    """D&D 游戏注释示例"""
-    console.print(Panel.fit("D&D 游戏注释示例", style="bold green"))
-    
-    # 模拟一场 D&D 战斗
-    expressions = [
-        "1d20 + 5 # 攻击检定",
-        "2d6 + 3 # 伤害投掷",
-        "1d20 + 3 # 法术豁免检定",
-        "4d6kh3 # 力量属性投掷",
-        "2d20kh1 # 优势攻击检定",
-        "1d4 + 1 # 治疗药水"
-    ]
-    
-    table = Table(title="D&D 战斗记录")
-    table.add_column("表达式", style="cyan")
-    table.add_column("总点数", style="green")
-    table.add_column("注释", style="yellow")
-    table.add_column("结果", style="white")
-    
-    for expr in expressions:
-        result = oneroll.roll(expr)
-        total = result['total']
-        
-        # 根据注释类型判断结果
-        if "攻击检定" in result['comment']:
-            if total >= 15:
-                outcome = "命中!"
-            else:
-                outcome = "未命中"
-        elif "伤害投掷" in result['comment']:
-            outcome = f"造成 {total} 点伤害"
-        elif "豁免检定" in result['comment']:
-            if total >= 12:
-                outcome = "豁免成功"
-            else:
-                outcome = "豁免失败"
-        elif "属性投掷" in result['comment']:
-            outcome = f"属性值: {total}"
-        elif "优势" in result['comment']:
-            outcome = "优势投掷"
-        else:
-            outcome = "投掷完成"
-        
-        table.add_row(
-            expr,
-            str(total),
-            result['comment'],
-            outcome
-        )
-    
-    console.print(table)
-
-def rpg_session_example():
-    """RPG 会话记录示例"""
-    console.print(Panel.fit("RPG 会话记录示例", style="bold magenta"))
-    
-    # 模拟一个 RPG 会话
-    session_log = [
-        ("1d20 + 4 # 开锁检定", "尝试打开宝箱"),
-        ("3d6 # 宝箱陷阱伤害", "触发陷阱"),
-        ("1d20 + 2 # 敏捷豁免", "躲避陷阱"),
-        ("2d8 + 2 # 宝箱中的金币", "发现宝藏"),
-        ("1d100 # 随机遭遇", "探索洞穴"),
-        ("4d6kh3 # 新角色属性", "创建角色")
-    ]
-    
-    for expr, description in session_log:
-        result = oneroll.roll(expr)
-        console.print(f"[bold]{description}[/bold]")
-        console.print(f"  投掷: {expr}")
-        console.print(f"  结果: {result['total']}")
-        console.print(f"  注释: {result['comment']}")
-        console.print()
-
-def complex_expression_comment_example():
-    """复杂表达式注释示例"""
-    console.print(Panel.fit("复杂表达式注释示例", style="bold red"))
-    
-    complex_expressions = [
-        "2d6 + 3d8 - 5 # 复合伤害计算",
-        "(2d6 + 3) * 2 # 暴击伤害",
-        "4d6!kh3 # 爆炸骰子属性投掷",
-        "6d6dl2kh3 # 复杂修饰符测试",
-        "3d6r1 + 2d8ro2 # 重投组合攻击"
-    ]
-    
-    for expr in complex_expressions:
-        try:
-            result = oneroll.roll(expr)
-            console.print(f"[bold cyan]{expr}[/bold cyan]")
-            console.print(f"  总点数: [bold green]{result['total']}[/bold green]")
-            console.print(f"  注释: [bold yellow]{result['comment']}[/bold yellow]")
-            console.print(f"  详情: {result['details']}")
-            console.print()
-        except Exception as e:
-            console.print(f"[red]错误: {expr} - {e}[/red]")
-            console.print()
-
-def comment_statistics_example():
-    """注释统计示例"""
-    console.print(Panel.fit("注释统计示例", style="bold yellow"))
-    
-    # 统计不同类型的投掷
-    attack_rolls = oneroll.roll_multiple("1d20 + 5 # 攻击检定", 10)
-    damage_rolls = oneroll.roll_multiple("2d6 + 3 # 伤害投掷", 10)
-    
-    # 计算攻击命中率
-    attack_totals = [r['total'] for r in attack_rolls]
-    hit_count = sum(1 for total in attack_totals if total >= 15)
-    hit_rate = hit_count / len(attack_totals) * 100
-    
-    # 计算平均伤害
-    damage_totals = [r['total'] for r in damage_rolls]
-    avg_damage = sum(damage_totals) / len(damage_totals)
-    
-    console.print(f"攻击检定统计:")
-    console.print(f"  命中率: {hit_rate:.1f}% ({hit_count}/{len(attack_totals)})")
-    console.print(f"  平均攻击值: {sum(attack_totals) / len(attack_totals):.1f}")
-    console.print()
-    
-    console.print(f"伤害投掷统计:")
-    console.print(f"  平均伤害: {avg_damage:.1f}")
-    console.print(f"  最小伤害: {min(damage_totals)}")
-    console.print(f"  最大伤害: {max(damage_totals)}")
-    console.print()
-
-def error_handling_example():
-    """错误处理示例"""
-    console.print(Panel.fit("错误处理示例", style="bold red"))
-    
-    # 测试各种边界情况
-    test_cases = [
-        "3d6 # 正常注释",
-        "3d6 #",  # 空注释
-        "3d6",    # 无注释
-        "3d6 # 这是一个很长的注释，用来测试长注释的显示效果",
-        "3d6 # 中文注释测试",
-        "3d6 # 特殊字符: !@#$%^&*()",
-    ]
-    
-    for expr in test_cases:
-        try:
-            result = oneroll.roll(expr)
-            comment = result.get('comment', '')
-            if comment:
-                console.print(f"✅ {expr}")
-                console.print(f"   注释: '{comment}'")
-            else:
-                console.print(f"✅ {expr} (无注释)")
-        except Exception as e:
-            console.print(f"❌ {expr} - 错误: {e}")
-        console.print()
-
-def main():
-    """主函数"""
-    console.print(Panel.fit("OneRoll 注释功能示例", style="bold blue"))
-    console.print("展示如何使用 # 在骰子表达式中添加注释\n")
-    
-    basic_comment_example()
-    dnd_comment_example()
-    rpg_session_example()
-    complex_expression_comment_example()
-    comment_statistics_example()
-    error_handling_example()
-    
-    console.print(Panel.fit("示例完成！注释功能让骰子投掷更有意义！", style="bold green"))
-
-if __name__ == "__main__":
-    main()
diff --git a/examples/sdk_example.py b/examples/sdk_example.py
deleted file mode 100644
index 6801686..0000000
--- a/examples/sdk_example.py
+++ /dev/null
@@ -1,165 +0,0 @@
-#!/usr/bin/env python3
-"""
-OneRoll SDK 使用示例
-
-展示如何使用 OneRoll 作为 Python SDK 进行骰子投掷。
-"""
-
-import oneroll
-from rich.console import Console
-from rich.table import Table
-from rich.panel import Panel
-
-console = Console()
-
-def basic_usage_example():
-    """基本使用示例"""
-    console.print(Panel.fit("基本使用示例", style="bold blue"))
-    
-    # 使用便捷函数
-    result = oneroll.roll("3d6 + 2")
-    console.print(f"3d6 + 2 = {result['total']}")
-    
-    # 使用 OneRoll 类
-    roller = oneroll.OneRoll()
-    result = roller.roll("4d6kh3")
-    console.print(f"4d6kh3 = {result['total']}")
-    
-    # 简单投掷
-    total = oneroll.roll_simple(2, 10)
-    console.print(f"2d10 = {total}")
-
-def dnd_example():
-    """D&D 游戏示例"""
-    console.print(Panel.fit("D&D 游戏示例", style="bold green"))
-    
-    roller = oneroll.OneRoll()
-    
-    # 属性投掷
-    attr_result = roller.roll(oneroll.CommonRolls.ATTRIBUTE_ROLL)
-    console.print(f"属性投掷 (4d6kh3): {attr_result['total']}")
-    
-    # 攻击投掷
-    attack_roll = roller.roll("1d20 + 5")
-    console.print(f"攻击投掷 (1d20 + 5): {attack_roll['total']}")
-    
-    # 伤害投掷
-    damage_roll = roller.roll("2d6 + 3")
-    console.print(f"伤害投掷 (2d6 + 3): {damage_roll['total']}")
-    
-    # 优势/劣势投掷
-    advantage_roll = roller.roll(oneroll.CommonRolls.D20_ADVANTAGE)
-    console.print(f"优势投掷 (2d20kh1): {advantage_roll['total']}")
-
-def statistics_example():
-    """统计示例"""
-    console.print(Panel.fit("统计示例", style="bold yellow"))
-    
-    # 多次投掷统计
-    stats = oneroll.roll_statistics("3d6", 100)
-    
-    table = Table(title="3d6 投掷统计 (100次)")
-    table.add_column("统计项", style="cyan")
-    table.add_column("数值", style="green")
-    
-    table.add_row("最小值", str(stats['min']))
-    table.add_row("最大值", str(stats['max']))
-    table.add_row("平均值", f"{stats['mean']:.2f}")
-    table.add_row("总和", str(stats['total']))
-    
-    console.print(table)
-
-def modifier_example():
-    """修饰符示例"""
-    console.print(Panel.fit("修饰符示例", style="bold magenta"))
-    
-    roller = oneroll.OneRoll()
-    
-    # 爆炸骰子
-    explode_result = roller.roll("2d6!")
-    console.print(f"爆炸骰子 (2d6!): {explode_result['total']}")
-    
-    # 取高
-    keep_high_result = roller.roll("4d6kh3")
-    console.print(f"取高 (4d6kh3): {keep_high_result['total']}")
-    
-    # 取低
-    keep_low_result = roller.roll("4d6kl2")
-    console.print(f"取低 (4d6kl2): {keep_low_result['total']}")
-    
-    # 丢弃高
-    drop_high_result = roller.roll("5d6dh1")
-    console.print(f"丢弃高 (5d6dh1): {drop_high_result['total']}")
-    
-    # 重投
-    reroll_result = roller.roll("3d6r1")
-    console.print(f"重投 (3d6r1): {reroll_result['total']}")
-
-def complex_expression_example():
-    """复杂表达式示例"""
-    console.print(Panel.fit("复杂表达式示例", style="bold red"))
-    
-    roller = oneroll.OneRoll()
-    
-    expressions = [
-        "2d6 + 3d8 - 5",
-        "(2d6 + 3) * 2",
-        "4d6!kh3",
-        "6d6dl2kh3",
-        "3d6r1 + 2d8ro2",
-        "10d10kh1",
-        "2d20kh1 + 5"
-    ]
-    
-    for expr in expressions:
-        try:
-            result = roller.roll(expr)
-            console.print(f"{expr:15} = {result['total']:2d}")
-        except Exception as e:
-            console.print(f"{expr:15} = 错误: {e}")
-
-def error_handling_example():
-    """错误处理示例"""
-    console.print(Panel.fit("错误处理示例", style="bold red"))
-    
-    invalid_expressions = [
-        "0d6",
-        "3d0",
-        "d6",
-        "3d",
-        "3d6 / 0",
-        "invalid"
-    ]
-    
-    for expr in invalid_expressions:
-        try:
-            result = oneroll.roll(expr)
-            console.print(f"{expr:15} = {result['total']}")
-        except Exception as e:
-            console.print(f"{expr:15} = 错误: {e}")
-
-def main():
-    """主函数"""
-    console.print(Panel.fit("OneRoll SDK 使用示例", style="bold blue"))
-    
-    basic_usage_example()
-    console.print()
-    
-    dnd_example()
-    console.print()
-    
-    statistics_example()
-    console.print()
-    
-    modifier_example()
-    console.print()
-    
-    complex_expression_example()
-    console.print()
-    
-    error_handling_example()
-    
-    console.print(Panel.fit("示例完成！", style="bold green"))
-
-if __name__ == "__main__":
-    main()
diff --git a/src/oneroll/__init__.py b/src/oneroll/__init__.py
index a57cfee..85ec807 100644
--- a/src/oneroll/__init__.py
+++ b/src/oneroll/__init__.py
@@ -32,7 +32,7 @@ from ._core import (
     roll_simple as _roll_simple,
 )
 
-__version__ = "1.0.1"
+__version__ = "1.0.2"
 __author__ = "HsiangNianian"
 __description__ = "高性能骰子表达式解析器"