更新文档，修正注释和示例，添加新功能说明

Alumopper · Alumopper · commit 9af251419562 · 2025-03-06T20:58:06.000+08:00
diff --git a/docs/en/quickstart/01project/01create-project.md b/docs/en/quickstart/01project/01create-project.md
@@ -2,6 +2,40 @@
 lastUpdated: true
 ---
 
-# Create a Project
+# Getting Started
 
-TODO
+MCFPP currently offers two usage methods: directly using the command line or building with Gradle. For simple functionalities, the command line is recommended. Gradle provides more extensive support, such as MNI.
+
+## Compiling with Command Line
+
+You can download the latest version of the MCFPP compiler from the release page on [GitHub](https://github.com/MinecraftFunctionPlusPlus/MCFPP/releases), which should be a Jar file. MCFPP requires Java 21 or higher. You can place it anywhere as long as you can locate it in the command line.
+
+First, create a project folder and a project configuration file. You can find the detailed format of the project configuration file in the next section. In this example, we create an `example.json` as the project configuration file.
+
+```json
+{
+  "description": "",
+  "namespace": "mcfpp",
+  "targetPath": "D:\\.minecraft\\saves\\MCFPP Example\\datapacks"
+}
+```
+
+Next, create a simple mcfpp file, such as `example.mcfpp`:
+
+```mcfpp
+func hello(){
+    print("Hello World");
+}
+```
+
+Then, compile the project using the command line:
+
+```shell
+java -jar mcfpp.jar example.json
+```
+
+This command compiles `example.mcfpp` into a data pack and outputs it to the `D:\.minecraft\saves\MCFPP Example\datapacks` directory. You can then load the data pack in the game and run `function mcfpp:hello` to see the effect.
+
+## Building with Gradle
+
+TODO
diff --git a/docs/en/quickstart/01project/02config-file.md b/docs/en/quickstart/01project/02config-file.md
@@ -8,22 +8,27 @@ The project configuration file for MCFPP is a JSON file, typically stored in the
 
 ```json
 {
-    // List of project file paths. Use wildcard symbols to select all files.
-    "files": [
-        "src/main/mcfpp/**"
-    ],
+    // The target Minecraft version to compile for. Only official version numbers are supported.
+    "version": "1.21.4",
     // The source code directory of the project. The namespace of the files is determined by their relative path to the source code directory.
-    "sourcePath": "src/main/mcfpp",
+    "sourcePath": "src/main/mcfpp/**",
     // Description of the datapack. This is a raw JSON text.
     "description": "",
     // The default namespace for the datapack, which will determine the namespace for datas, for instance storage in the package.
     "namespace": "test",
+    // The jar-packaged libraries to be called.
+    "jar": [],
     // The output path for the datapack. The datapack and library files will be output to this directory.
-    "targetPath": "src/main/resources/lib",
+    "targetPath": "build",
     // Whether to *not* generate a datapack. Default is false.
     "noDatapack": false,
-    // Whether to *ignore* the standard library. Default is false. If set to true, the MCFPP standard library will not be referenced.
-    "ignoreStdLib": false,
-    // Whether it is a library. Default is false. Libraries do not need to have an entry function.
-    "isLib": false
+    // Compilation arguments
+    "compileArgs": [
+        // Compile in debug mode (for compiler development)
+        "-debug", 
+        // Ignore the standard library
+        "-ignoreStdLib",
+        // Whether it is a library
+        "-isLib"
+    ]
 }
diff --git a/docs/en/quickstart/02base/02comments.md b/docs/en/quickstart/02base/02comments.md
@@ -38,4 +38,4 @@ This is a document comment
 }#
 ```
 
-Document comment can include some special tags used to tag the content of the comment. Details in the Document chapter (TODO).
+Document comment can include some special tags used to tag the content of the comment. Details in the [Document](../13doc/01doc-comment.md)。
diff --git a/docs/en/quickstart/02base/03logic-statements.md b/docs/en/quickstart/02base/03logic-statements.md
@@ -100,4 +100,4 @@ for (int i = 0; i < 10; i++){
 
 In this example, when the value of `i` is `5`, `break`will jump out of the loop; when the value of `i` is `3`, `continue` will jump this loop, go to the next loop directly. So, the change of I in each loop are:`0`，`1`，`2`，`4`，`5`, and finally jump out.
 
-`break` and `continue` statement only can be used in the loop
+`break` and `continue` only can be used in the loop
diff --git a/docs/en/quickstart/02base/04top-statements.md b/docs/en/quickstart/02base/04top-statements.md
@@ -2,7 +2,7 @@
 lastUpdated: true
 ---
 
-# Top statement<Badge type="warning">May Change</Badge>
+# Top statement<Badge type="tip">Future Feature</Badge>
 
 MCFPP allows programming statements at the start of the file and don't need to define any function, that's the top statement. Top statement places in a hidden function, each file have one and only one of this function, and it cannot be called externally. Its returned value’s type is `void`.
 
diff --git a/docs/en/quickstart/02base/05original-command.md b/docs/en/quickstart/02base/05original-command.md
@@ -29,3 +29,7 @@ func test(){
 ```
 
 This will insert the raw text from the `insert` function's parameter into the `test` function. It's important to note that the `insert` function's parameter is a string, so you can insert any content. This also means that the compiler will not perform any checks on the command format.
+
+## Command Interpolation
+
+See [JVM Accessors](../11mni/05access.md) for more information.
diff --git a/docs/en/quickstart/04function/01define-and-call.md b/docs/en/quickstart/04function/01define-and-call.md
@@ -4,8 +4,6 @@ lastUpdate: true
 
 # Define and call
 
-The way of define function in MCFPP has some differences with C/Java, and more similar to the grammar of Python.
-
 ## Function definition
 
 In MCFPP, the grammar of define a function is shown below:
diff --git a/docs/en/quickstart/05class/05miscellaneous.md b/docs/en/quickstart/05class/05miscellaneous.md
@@ -0,0 +1,31 @@
+---
+lastUpdate: true
+---
+
+# Miscellaneous
+
+## Base Entity
+
+In the example at the beginning of this chapter, you may have noticed the line `@Base<"creeper">`. This line of code is called an **annotation**, which we will discuss in later chapters. Using the `@Base<"creeper">` annotation on the line before the class definition specifies which entity this entity template is based on. This entity is the base entity.
+
+Generally, most entities cannot store custom data well directly, so when the base entity is not `item_display` or `marker`, a `marker` entity will ride on this entity to store the custom fields of the entity template.
+
+The base entity has the tag `<namespace>_class_<classname>_pointer`, while the entity used to store data has the tag `<namespace>_class_<classname>_pointer_data`.
+
+::: info
+After 24w10a, all entities can store custom data through the `minecraft:custom_data` entity component. This means that in future versions of mcfpp, classes composed of any type of base entity will store data uniformly in the `minecraft:custom_data` component.
+:::
+
+## Lifecycle of Entity Templates
+
+The lifecycle of an entity template is consistent with that of the base entity. When the base entity is removed, the entity template is also removed. This process is automatically handled by the garbage collector (GC).
+
+Of course, you can manually release memory using the `dispose` function <Badge type="tip">Future Feature</Badge>:
+
+```mcfpp
+
+SuperCreeper p = SuperCreeper("Super Creeper");
+
+p.dispose();
+
+```
diff --git a/docs/en/quickstart/08nbt/02list.md b/docs/en/quickstart/08nbt/02list.md
@@ -41,6 +41,7 @@ The MCFPP standard library provides a series of functions for list operations.
 | `addAll` | `list<T> elements` | `void` | Adds a group of elements to the list |
 | `insert` | `int index, T element` | `void` | Inserts an element at a specified position |
 | `removeAt` | `int index` | `void` | Removes the element at the specified position |
+| `remove` | `T element` | `void` | Removes the specified element |
 | `indexOf` | `T element` | `int` | Returns the index of the specified element |
 | `lastIndexOf` | `T element` | `int` | Returns the last index of the specified element |
 | `contains` | `T element` | `bool` | Checks if the list contains the specified element |
diff --git a/docs/en/quickstart/08nbt/03dict.md b/docs/en/quickstart/08nbt/03dict.md
@@ -45,3 +45,4 @@ Dictionaries cannot be iterated over, and you cannot retrieve a list of keys or
 | `containsKey` | `string key` | `bool` | Checks if the dictionary contains a specified key |
 | `merge` | `dict dict` | `void` | Merges two dictionaries |
 | `remove` | `string key` | `void` | Removes the key-value pair for the specified key |
+| `clear` | `void` | `void` | Clears the dictionary |
diff --git a/docs/en/quickstart/08nbt/04map.md b/docs/en/quickstart/08nbt/04map.md
@@ -32,12 +32,16 @@ The MCFPP standard library provides a series of functions to manipulate `map`.
 | `containsKey` | `string key` | `bool` | Checks if the `map` contains the specified key |
 | `containsValue` | `T value` | `bool` | Checks if the `map` contains the specified value |
 | `isEmpty` | `void` | `bool` | Checks if the `map` is empty |
-| `getKeys` | `void` | `list<string>` | Retrieves all keys in the `map` |
-| `getValues` | `void` | `list<T>` | Retrieves all values in the `map` |
 | `remove` | `string key` | `void` | Removes the key-value pair for the specified key |
 | `merge` | `map<T> map` | `void` | Merges two `maps` |
 | `size` | `void` | `int` | Returns the size of the `map` |
 
+As well as some properties:
+
+| Property Name | Type | Description|
+| --- | --- | --- |
+| `keys`| `string`| Gets all the keys in the `map`|
+
 ## map Traversal <Badge type="tip" text="Future Feature" />
 
 You can use the `foreach` loop to easily traverse all key-value pairs in a `map`.
@@ -81,9 +85,8 @@ When stored, the structure of the `map` would look like this:
 namespace.stack_frame:[
     {
         m:{
-            key:["qwq","owo","nya"],        // Key list
-            value:["pwp","uwu","meow"],     // Value list
-            data:{
+            keys:["qwq","owo","nya"],        // Key list
+            keyValueSet:{
                 "qwq":"pwp","owo":"uwu","nya":"meow"    // Key-value pairs, similar to a dict
             }    
         }
diff --git a/docs/en/quickstart/09template/02template-nest.md b/docs/en/quickstart/09template/02template-nest.md
@@ -41,3 +41,15 @@ func main(){
 ```
 
 Apparently, using the same type as a member within a Data Template is not allowed.
+
+## Anonymous Definition
+
+In a Data Template, an anonymous Data Template can be defined as a member type:
+
+```mcfpp
+data B{
+    int valueB;
+    data{
+        int valueA;
+    } dataA;
+}
diff --git a/docs/en/quickstart/11mni/01mni-framework.md b/docs/en/quickstart/11mni/01mni-framework.md
@@ -49,4 +49,4 @@ public class System extends MNIMethodContainer {
 }
 ```
 
-In the following sections, we will discuss in detail how to use the MNI framework.
+In the following sections, we will discuss in detail how to use the MNI framework.
diff --git a/docs/en/quickstart/11mni/04annotation.md b/docs/en/quickstart/11mni/04annotation.md
@@ -2,7 +2,7 @@
 lastUpdate: true
 ---
 
-# Annotations <Badge type="tip">WIP</Badge>
+# Annotations
 
 You can add annotations to classes, data templates, and method declarations by using the `@` symbol followed by the annotation name and a read-only parameter list. Annotations are part of the MNI framework and only exist during the compilation phase.
 
diff --git a/docs/en/quickstart/13doc/01doc-comment.md b/docs/en/quickstart/13doc/01doc-comment.md
@@ -0,0 +1,74 @@
+---
+lastUpdated: true
+---
+
+# Documentation Comments <Badge type="tip">Future Feature</Badge>
+
+As the third type of comment in MCFPP, documentation comments can be used to automatically generate documentation for your project. MCFPP's documentation comments are a mix of tag syntax and Markdown. You can use tag comments to provide necessary key information and Markdown to write detailed documentation.
+
+## Syntax
+
+Documentation comments start with `#{` and end with `#}`, with the content in between being the documentation comment. Each line of the documentation comment can start with `#`, which will not be considered part of the comment.
+
+Tag comments must be written before the Markdown content.
+
+Documentation comments can be written above any declaration, but local variable documentation comments will not be extracted into the generated documentation and are only used for IDE hints.
+
+Here is an example of a documentation comment:
+
+```mcfpp
+
+#{
+    @base Creeper
+
+    Implementation class for Super Creeper
+}#
+@Base<"creeper">
+class SuperCreeper{
+
+    #{
+        List of effects the creeper will give
+    }#
+    list effectList = ["wither", "poison", "slowness", "hunger", "blindness", "weakness"];
+
+    #{
+        @return A random effect
+
+        Get a random effect
+    }#
+    func getEffect() -> string {
+        return effectList.random();
+    }
+
+    override func tick(){
+        if(@a[distance = 0..5].exist()){
+            effect(@a[distance = 0..5], getEffect(), 1, 10);
+        }
+    }
+
+}
+```
+
+## Tags
+
+Some tags can only be used for entity templates, some only for functions, some only for variables or members, and some are general.
+
+### General Tags
+
+- `@see Reference`: Specifies a reference document.
+- `@since Version`: Specifies the version from which it was introduced.
+- `@deprecated Version`: Specifies the version from which it was deprecated.
+- `@version Version`: Specifies the version number.
+- `@author Author`: Specifies the author.
+
+### Entity Template Tags
+
+- `@base Description`: Specifies the base entity.
+- `@param GenericParameterName Description`: Specifies the description of a generic parameter.
+
+### Function Tags
+
+- `@return Description`: Specifies the return value description.
+- `@throws Exception Description`: Specifies the description of thrown exceptions.
+- `@param Parameter Description`: Specifies the description of a parameter.
+- `@context <entity|pos|rotation|dimension> Description`: Specifies the context description, usually the execution environment of the function.
diff --git a/docs/zh/quickstart/01project/02config-file.md b/docs/zh/quickstart/01project/02config-file.md
@@ -14,17 +14,22 @@ MCFPP的工程配置文件是一个json文件，一般存放在这个工程的
     "sourcePath": "src/main/mcfpp/**",
     //数据包的描述。是一个原始JSON文本
     "description": "",
-    //数据包的默认命名空间，将会决定数据包中storage等数据的命名空间
-    "rootNamespace": "test",
+    //数据包的默认命名空间
+    "namespace": "test",
+    //调用的jar包装的库
+    "jar": [],
     //数据包的输出路径。数据包、库文件将会输出在此目录下
-    "targetPath": "src/main/resources/lib",
+    "targetPath": "build",
     //是否 *不* 生成数据包。默认为false
     "noDatapack": false,
-    //是否 *忽略* 标准库。默认为false。如果为true，将不会引用mcfpp的标准库。 
-    "ignoreStdLib": false,
-    //是否是库。默认为false。库不需要拥有一个入口函数
-    "isLib": false,
-    //生成注释的级别
-    "commentLevel": "debug"
+    //编译参数
+    "compileArgs": [
+        //以调试模式编译（用于编译器开发）
+        "-debug", 
+        //是否忽略标准库
+        "-ignoreStdLib",
+        //是否是库
+        "-isLib"
+    ]
 }
 ```
diff --git a/docs/zh/quickstart/02base/01variables.md b/docs/zh/quickstart/02base/01variables.md
@@ -117,7 +117,7 @@ int i = 5;  #编译器记住了这个变量的值为5
 i += 7;     #编译器直接将i的值记为12，不会输出记分板命令
 int j = i;  #编译器同样也知道了j的值
 
-import int x;
+dynamic int x;
 j = x;      #编译器丢失了对j具体值的跟踪
 j += 1;     #编译器会输出记分板命令
 ```
diff --git a/docs/zh/quickstart/02base/02comments.md b/docs/zh/quickstart/02base/02comments.md
@@ -38,4 +38,4 @@ lastUpdated: true
 }#
 ```
 
-文档注释可以包含一些特殊的标签，用来标记注释的内容。详细参考文档章节。
+文档注释可以包含一些特殊的标签，用来标记注释的内容。详细参考[文档](../13doc/01doc-comment.md)。
diff --git a/docs/zh/quickstart/02base/03logic-statements.md b/docs/zh/quickstart/02base/03logic-statements.md
@@ -64,24 +64,6 @@ do{
 }while (condition);
 ```
 
-## for语句
-
-`for`语句是循环的一种稍复杂的版本，它的语法如下：
-
-```mcfpp
-for (forinit; condition; forupdate){
-    #code
-}
-```
-
-`forinit`是一个初始化表达式，它用来初始化循环变量。`condition`是一个布尔表达式，它用来判断循环是否继续。`forupdate`是一个更新表达式，它用来更新循环变量。`#code`代表了循环体，即循环体中的代码。在运行的时候，`for`语句的执行过程如下：
-
-1. 执行`forinit`，初始化循环变量。
-2. 判断`condition`的值，如果`condition`的值为`true`，则执行`#code`代表的代码块，然后执行`forupdate`，更新循环变量，再次判断`condition`的值。
-3. 如果`condition`的值为`false`，则退出循环。
-
-`for`循环中，`forinit`声明的变量只在`for`循环中有效。
-
 ## break和continue语句
 
 `break`语句用来跳出整个循环，`continue`语句用来跳过本次循环。例如：
diff --git a/docs/zh/quickstart/02base/04top-statements.md b/docs/zh/quickstart/02base/04top-statements.md
@@ -2,7 +2,7 @@
 lastUpdated: true
 ---
 
-# 顶层语句<Badge type="warning">可能更改</Badge>
+# 顶层语句<Badge type="tip">未来特性</Badge>
 
 在MCFPP中，允许在文件的开始直接编写语句而无需额外定义函数，即顶层语句。顶层语句处于一个隐式的函数中，这个函数每个文件有且只有一个，且不能被外部调用。它的返回值类型为`void`。
 
diff --git a/docs/zh/quickstart/02base/05original-command.md b/docs/zh/quickstart/02base/05original-command.md
@@ -29,3 +29,7 @@ func test(){
 ```
 
 将会将`insert`参数中的原文插入到test函数中。值得注意的是，`insert`函数的参数是一个字符串，因此你可以在其中插入任何内容，这同时意味着编译器不会对命令格式进行任何检查。
+
+## 命令插值
+
+参见[JVM访问符](../11mni/05access.md)
diff --git a/docs/zh/quickstart/03namespace/01namespace.md b/docs/zh/quickstart/03namespace/01namespace.md
@@ -18,4 +18,4 @@ func test(){    # test:test函数
 
 一个文件中只能声明一次命名空间。
 
-若没有声明命名空间，文件的命名空间将会由文件路径相对于源代码路径的相对路径决定。例如，假设源代码目录为`src/main/mcfpp`，那么文件`src/main/mcfpp/test/test.mcfpp`的命名空间将会是`test.test`。源代码路径通过工程配置文件中的`sourcePath`决定。
+若没有声明命名空间，文件的命名空间将会由文件路径相对于源代码路径的相对路径决定。例如，假设源代码目录为`src/main/mcfpp`，项目命名空间为`test`，那么文件`src/main/mcfpp/uwu/test.mcfpp`的命名空间将会是`test:uwu`。源代码路径通过工程配置文件中的`sourcePath`决定。
diff --git a/docs/zh/quickstart/04function/01define-and-call.md b/docs/zh/quickstart/04function/01define-and-call.md
diff --git a/docs/zh/quickstart/05class/05miscellaneous.md b/docs/zh/quickstart/05class/05miscellaneous.md
diff --git a/docs/zh/quickstart/08nbt/02list.md b/docs/zh/quickstart/08nbt/02list.md
diff --git a/docs/zh/quickstart/08nbt/03dict.md b/docs/zh/quickstart/08nbt/03dict.md
diff --git a/docs/zh/quickstart/08nbt/04map.md b/docs/zh/quickstart/08nbt/04map.md
diff --git a/docs/zh/quickstart/09template/02template-nest.md b/docs/zh/quickstart/09template/02template-nest.md
diff --git a/docs/zh/quickstart/11mni/04annotation.md b/docs/zh/quickstart/11mni/04annotation.md

Original file line number	Diff line number	Diff line change
`@@ -100,4 +100,4 @@ for (int i = 0; i < 10; i++){`
`100`	`100`
`101`	`101`	In this example, when the value of `i` is `5`, `break`will jump out of the loop; when the value of `i` is `3`, `continue` will jump this loop, go to the next loop directly. So, the change of I in each loop are:`0`，`1`，`2`，`4`，`5`, and finally jump out.
`102`	`102`
`103`		-`break` and `continue` statement only can be used in the loop
	`103`	+`break` and `continue` only can be used in the loop