docs(@test): explain snapshot test

[illusory0x0]

related issues: moonbitlang/moon#720

[peter-jerry-ye-code-review]

Inconsistent documentation style between functions

Category
Maintainability
Code Snippet
pub fn fail[T](msg : String, loc~ : SourceLoc = _) -> T!
pub fn write(self : T, obj : &Show) -> Unit
Recommendation
Add parameter descriptions in the documentation for all functions following the same format. For example:

///| Expected used in test block, don't catch this error.
///  
/// Parameters:
///   - msg: The error message to display
///   - loc~: Source location of the failure (optional)
/// Produces an error message similar to @builtin.fail.

Reasoning
Consistent documentation style improves readability and makes it easier for developers to understand function usage. Currently, the documentation varies in detail level between functions.

Example code could be more comprehensive

Category
Maintainability
Code Snippet
///| Use snapshot in test block end, only can be used once.
///
/// ```
/// test {
/// let t = new("test.txt")
/// t.writeln("hello")
/// t.snapshot!(filename="test.txt") // actual test block end
/// t.writeln("world") // unreachable code
/// // Cann't found world in `test.txt`
/// }
Recommendation
Improve example code by showing both successful and failure cases, and fix the typo in the comment:

/// ```
///  test {
///   let t = new("test.txt")
///   t.writeln("hello")
///   t.snapshot!(filename="test.txt") // Write snapshot and end test
///   
///   // This won't execute:
///   t.writeln("world") 
///   // Cannot find `world` in `test.txt`
/// }
/// ```
**Reasoning**
The current example contains a typo ('Cann't') and could better illustrate the consequences of the snapshot function being a terminal operation. Clear examples help prevent misuse of the API.

</details>
<details>

<summary> Missing return type documentation </summary>

**Category**
Correctness
**Code Snippet**
pub fn fail[T](msg : String, loc~ : SourceLoc = _) -> T!
pub fn write(self : T, obj : &Show) -> Unit
**Recommendation**
Add return type documentation for all functions. For example:
```moonbit
///| Expected used in test block, don't catch this error.
///  
/// Parameters:
///   - msg: The error message to display
///   - loc~: Source location of the failure (optional)
/// Returns:
///   Never returns normally, always fails with the given message
/// Produces an error message similar to @builtin.fail.

Reasoning
Return type documentation helps developers understand the expected behavior of functions, especially for functions that return special types like T! (failure type) or Unit.

[coveralls]

Pull Request Test Coverage Report for Build 6484

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 1 unchanged line in 1 file lost coverage.
• Overall coverage decreased (-0.02%) to 92.682%

---

Files with Coverage Reduction	New Missed Lines	%
bench/stats.mbt	1	76.32%

Totals
Change from base Build 6474:	-0.02%
Covered Lines:	6117
Relevant Lines:	6600

---

💛 - Coveralls

[peter-jerry-ye]

We'll try to solve the issue with the snapshot testing